Customizing ERPNext -- will bench update later override our changes?

Hi all
We have been testing ERPNext and it looks like it might suit our needs…
However, we need to make some modifications to the Journal Entry feature to account for taxes. Our plan is to add a “Taxes and Charges” field to the Journal Entry form and then modify the make_gl_entries in the journay_entry.py file to read the new field and create 2 more ledger entries with amounts equating to the tax calculated for the entry based on the Tax Rule.
The problem is, we are worried that when we do an update, our changes will be overwritten. What is the standard approach to doing this type of thing?

If you change the core, then you will have to manage the merges your self.

If you think this feature can be made standard, you should get it added in the core so you wont have any future conflicts

Thanks for the reply. I’m very new to this whole open source thing… so I’m not sure how to do either of these things? Can you please recommend me what to do? Is there some kind of tutorial?

  1. How do I request to add code to the core?
  2. Perhaps more importantly, how do I make this customization? Should I make a custom app? I would like to know what is the standard way to go about doing something like this?

Thanks

Kim

@Luesak_Luesukprasert if you feel your changes are generic you can give a pull request otherwise you can create a custom app and keep your changes and link it through hooks.py

Thanks again.

REGARDING ADDING TO THE CORE
I’ve used source control via IDEs like Intelli-J and Visual Studio… working on company internal projects. But I’ve never worked with the opensource model… so all the terminologies are not familiar. How do “checkout” and “commit” changes to the project? What IDE do you guys typically use? Can you make some recommendations. The feature I described above has been requested by many users in the community. And I think it’s a fairly common thing to do. So it would be a good candidate for adding to the core.

I guess I will start here: https://guides.github.com/activities/hello-world/

ABOUT CUSTOM APP
I watched some videos and read some tutorial, it seems that the UI customizations are done via customizing the form on the ERPNext system itself. And then the py scripts are created in the file system. Is that right? If I customize the form not in code… when updating… would the customized form get overwritten? I assume the customization of the form is saved somewhere in the DB?

Hi @Luesak_Luesukprasert,

The source control for ERPNext is GitHub. There are many guides online. But the general idea is this. You “fork” the ERPNext repository. This is somewhat equivalent to “checkout”. You make your changes. Next, you submit a Pull Request. That is equivalent to requesting a commit. The owners of the ERPNext repository review your Pull Request. If they agree…they merge your changes into the standard code.

Also, in Frappe there is the concept of a custom App. The App has its own sub-folder in the frappe directory. Anything you create for that App is stored in that sub-folder. For example, maybe you want an App for a music playlist. You might create DocTypes for Song, Artist, Playlist. These would reside in the App’s subfolder. You can save/export your App. And later re-apply it to any ERPNext installation. This essentially allows you to create your own code, without worrying about it being overwritten by ERPNext core. However, this App code is somewhat standalone. You can create new features. But your App isn’t modifying the core DocTypes like Customer, Supplier, or Sales Order.

So. We end up with 3 development possibilities:

  1. You create your own App. In this case, ERPNext changes will not overwrite your App.
  2. You make changes to the core ERPNext, submit a Pull Request, and they are successfully merged into the master.
  3. You make changes to the core ERPNext, and they do not get merged into the master. Either because you didn’t submit a Pull Request. Or your request was denied.

I personally think often about #3. Because for customers, this will happen. A lot. I’ve already found clients and prospects asking about this. We must apply changes, and then later manually merge these changes back into our local forks/branches, when we migrate to a new ERPNext version. In this case, backups are essential. Take a complete backup of both your frappe folders and SQL, before doing an upgrade! Currently, there is no standard GUI tool for displaying and merging differences (this is one thing I miss from MS Dynamics). I suspect there are 3rd party tools we might leverage.

Regarding IDE’s. Frappe itself is an IDE. It can handle many (but not all) changes to ERPNext. Certainly you can begin there when creating DocTypes, Print Formats, and many other features.

As for the rest? There is no standard IDE we all use. Sometimes we use a simple text editor to modify a file. Some people use a tool called ATOM, with various plugins. With configuration, this could be somewhat equivalent to Visual Studio. Also, I occasionally use a tool called PyCharm for working with Python files, especially for debugging. For access to the SQL database (besides using the basic terminal), there are various IDEs such as MySQL Workbench, PhpMyAdmin, HeidiSQL, and many, many more.

To answer your final question. Most (but not all) code is saved in files in the frappe subdirectories. One notable exception I’ve found is Print Formats. If you create a custom HTML print format, that text is actually saved in a table in MariaDB. You can modify the text using the Frappe Desk. But it’s embedded in a column of SQL.

Hopefully the above information helps. It’s a very different world than Visual Studio, and other Microsoft tools. And it’s not perfect. But it’s actually quite good. The more time I spend in Linux, Frappe, and ERPNext, the more comfortable and confident I become.

~Brian

6 Likes

Supplementary to the excellent @brian_pond post above.

Firstly you will need to sign up for a free github account. Then it helps to have a have desktop github GUI app. There are lots of these available but Github Desktop might be worth trying out. The IDE I use is Atom which is just a text editor but has the advantage of built in github tools. Atom is currently adding more advanced IDE functionality with the Atom IDE project. All three apps are open source and maintained by github itself. If you were to choose Atom I would strongly suggest installing these additional community Atom Packages/Addons:

aligner, aligner-javascript, atom-beautify, atom-electron-snippets, atom-minify, autocomplete-python, atom-bootstrap3, busy-signal, color-picker, emmet, file-icons, git-plus, highlight-selected, intentions, linter (with the following linter add ons: linter-eslint, linter-jsonlint, linter-sass-lint, linter-ui-default, linter-xmllint), minimap, minimap-highlight-selected, pigments, pretty-json, project-manager, pigments, python-tools, xml-formater.

Sheesh… I just realised thats a load of packages but install them all anyway.

You can choose anyone of the many MySQL GUI apps available.

2 Likes

Brian,
Thank you for the very extensive response. That really helped to bridge the worlds of opensource and corporate software development for me. I guess I need to pick and choose which of the 3 options will be used when!

Thanks so much!

Kim

Thanks for the tools recommendations! I will sure to go try them!

Kim

One more thing… if the feature change requires changes to the doc type… e.g. the feature change above requires modification to the Journal Entry form… how do I submit a pull request for that? The form customization seems to be written to the DB somewhere.

Thanks

Kim

@brian_pond should I fork the master or the develop?

This is dependant on how your local dev environment is setup but in short.
Fork the original ERPNext github repo into your personal github account. Then clone your “fork” into your local dev machine’s ERPNext project folder. Now every time you make a change to a file on your local machine Atom will highlight which files have been modified compared to your “Fork” that is hosted on github. You can then merge,update,drop changes etc etc. Once you have completed your modifications. Go to the original ERPNext github repo and request that they “Pull” your changes from your github hosted repo. If they accept your changes they will get merged into the develop branch… which over a short period of time then gets merged into the master branch and goes live. HTH

OK Thanks @System19

So forking really imports all the branches to my github account. And then cloning takes the code into my dev machine.

Do I clone the master or should I clone the develop? I see that the develop branch has failed the Travis CI build… would cloning the develop branch make my dev system unable to run? and hence I won’t be able to test my changes?

What do people typically clone? There are so many branches… hotfix? develop? master? Which one do you guys use and why?

Kim

Sorry just saw your last post. When you “Fork” a repo you are in fact coping all the branches. But when selecting a branch to work on locally choose “develop”

So forking really imports all the branches to my github account. And then cloning takes the code into my dev machine.
Yes

Do I clone the master or should I clone the develop?
develop

I see that the develop branch has failed the Travis CI build… would cloning the develop branch make my dev system unable to run?
No. But in very odd cases where a change has been made that totally crashes the cloned app you can be sure the devs will roll back very quickly. In short just use develop.
Note The clone will never crash your local OS.

There are so many branches… hotfix? develop? master? Which one do you guys use and why?
As a general rule across all of github. master is the current live stable release and develop is…well develop. At the moment just ignore all the other branches as they are designed to allow a large centralised team to collaborate. In this case the core frappe team.

Thanks all!

One more thing… if the feature change requires changes to the doc type… e.g. the feature change above requires modification to the Journal Entry form… how do I submit a pull request for that? The form customization seems to be written to the DB somewhere.

Thanks

Kim

There are two ways to make changes in Frappe/ERPNext.
1: If the changes are very minor or just specific to your use case then you can use the Custom Field, Customize Form and Custom Script functionality built into the Frappe/ERPNext GUI. You can read up on these in the manual. These changes are stored in the Custom Field, Customize Form and Custom Script DB tables and as such do not interfere when updating.
2: If the changes you are making will be of use to other users (Which is likely as most business requirements are similar either by industry or geo-location) then make your changes to the Doctype. Then run bench migrate from your ~/frappe/frappe-bench/ folder. Reload your web browser and you changes should be reflected. If everything works then push your changes to your github hosted fork. Then go to the original Frappe/ERPNext github repo and click the big green button saying Pull Request. Job Done.

I modified the JSON file journal_entry.json… then run bench migrate… but nothing happens. Any cluse?

You could try:
bench reload-doc journal_entry
or
bench reload-doctype journal_entry

bench --help
lists both commands but I am not sure which one is current.

If this doesn’t work try:
bench restart

If this doesn’t work try
sudo service nginx restart
sudo supervisorctl restart all

One of these should work :slight_smile: