Guidance to work with Forks on Github for ERPNext only

[brian_pond]

This is a complicated topic. I will try to summarize the 4 different approaches, beginning with the least-complex scenario.

1. Making changes with the “Customize” button.

To make simple modifications (changing a DocField’s label, adding a new Naming Series, adding a DocField to an existing DocType), you may decide to use the Customize button.

When using this button, your changes are saved –in the SQL database– of your Site. The ERPNext code itself is not touched. So no git logs. (Exception: you may optionally choose to export your Customizations to JSON files in an App).

Advantages:

• Quick and easy to create minor changes.
• No need to think about git.

Disadvantages:

• Cannot do any complex changes, or significantly change how ERPNext behaves.
• Because the changes are stored in the database, the visibility of changes is “obscured”. There is no command like git diff that will show a developer Before vs. After. To understand what’s happened requires reviewing certain SQL tables and JSON files, and trying to grasp the original intent.

2. Writing your own App

If you need to --add-- to ERPNext (but not modify the existing functionality), you can decide to create your own App. Create new DocTypes and DocFields for your App. Write any necessary Python and JS code. When you’re ready, install the App on your Site.

You should definitely create a git repository for your custom App. But this repository will be entirely separated from the Frappe and ERPNext repositories.

Advantages:

• You can create new ideas, features, and functionality.

Disadvantages:

• You cannot modify what’s already in ERPNext. So you’re still limited by the Frappe framework’s code, and the ERPNext code. You can interface with them. But you cannot change them…

…unless you go with Approach #3:

3. Extending your App with ‘hooks’ and ‘fixtures’

To understand this approach, you must comprehend the fundamental nature of the Python and JavaScript programming languages. They are “interpreted” languages (sometimes called “scripting” languages). The code you write isn’t compiled into a binary executable. Instead the code stays in plain-text files. When your program runs, the Python/JS interpreter compiles “just-in-time”, before the code is required.

This behavior produces an interesting possibility:

1. You can write custom code in your App, which exists in your code files.
2. At runtime, your code “overrides/appends” the official ERPNext code.

This process is informally known as ‘guerilla patching’ or ‘monkey patching.’. It’s a bit of cleverness to change code behavior, without changing code files. Using this patch trick, you never edit the official Frappe/ERPNext code. But you still get the desired modification.

Advantages:

• You can create complex modifications and customizations.
• No changes to the official ERPNext code. No forking, or git comparisons/merging.

Disadvantages:

• You still have to put thought and effort into maintenance. When the official code changes (v12 → v13) your ‘monkey patch’ code will not be aware of this. Will the new, official changes break your patch code? Maybe. Maybe not. You have to test and review, to make sure your patch is still correctly implemented.
• It’s challenging for a 3rd party developer to login, and understand how ERPNext is behaving differently. You cannot run a git diff command, and view Official vs. Custom code. The code is now maintained in 2 places (official, patch). Hopefully the developer of the patch code does a good job documenting their changes.

4. Fork the official code, and maintain your own changes.

Finally, there is the “traditional” way of performing modifications, without patch code, hooks, or fixtures. You fork the official code. Create your own git branches. Modify whatever you want. And maintain your own fork from now on.

Advantages:

• This process is well-known, and well-documented. You’ll find countless articles and programs on the web for dealing with this.
• If you want to view differences between your ERPNext, and official ERPNext, just do a git diff command. You can quickly view a side-by-side comparison with GUI tools.

Disadvantages:

• You must maintain your own forks. This is not always easy or desireable.
• When synchronizing, you must handle the git merge process, often requiring you manually edit code files. This may be time-consuming. If so, you may choose to update your ERPNext less-frequently.
• Further reading:
  • Git
  • [Git Tricks for Maintaining a Long-Lived Fork]

Summary:
With great power, comes great responsibility.

The Frappe Framework offers many tools and methods for accomplishing your goals and needs. There is rarely a “right way” of accomplishing something. You have Options and Choices. Do what works best for you.

Personally, I usually write Custom Apps when I need to add functionality. But when I need to modify things, I usually choose Approach #4 (fork it). I dislike guerilla patching and Customization, for some of the reasons @guimorin mentioned.