Guide to splitting modules from ERPNext

Recently we have observed a need for splitting some modules from ERPNext monolith into separate app for various reasons. This article serves as guide for that transition.

Checklist

1. Plan the splitting of module at least 1 month ahead of next major release. We should give ample time to users to plan any activities that are required for migration like installing the app, which is a manual process on central.
2. Update documentation about deprecation and app installation process.
3. Add warning in Frappe/ERPNext that's visible to end user in current version. A bootstrap alert is good enough in most cases. Example.
4. Add a warning for sysadmins by making an empty patch that just prints warning about module deprecation / removal. You can add more info about migration or make this conditional based on usage. Example 1, Example 2.
5. [IMPORTANT] Add a patch in new app for migrating existing data, wherever required.
6. If there are any custom fields in the module, make sure to remove these fields in the patch.
7. Drop all doctypes, releated patches from develop branch. Make sure to trace and remove any imports that are present in other files. Ensure that PR conveys the breaking change.
8. Release notes for next major version should have "BREAKING CHANGES" section first with all the module removals.

Setting up new app

• Extract the module into a seperate repo using git-filter-repo.
• If there is any module specific code that is spread across other modules, clean it up and move to appropriate place in the new repo.
• Setup hooks.py file to run it as an app in ERPNext.
• Setup test data so that test suite can pass.
• Create a new readme file with detailed description of the app.
• Publish it as an app in FC marketplace.
• Setup a CI system similar to Frappe/ERPNext so you can be sure that your app is in installable and usable state at all times. This will be slightly different from Frappe or ERPNext as your app will depend on both of them. Reference CI for app that depends on ERPNext