From 8faf03988c643da7809b1047bc00fe51315b76ee Mon Sep 17 00:00:00 2001 From: Saurabh Date: Wed, 19 Jul 2017 18:02:05 +0530 Subject: [PATCH] [docs] documentation for release strategy and contribution guidelines --- bench/docs/contribution_guidelines.md | 46 +++++++++++++++++++++++++++ bench/docs/release_policy.md | 46 +++++++++++++++++++++++++++ bench/docs/releasing_frappe_erpext.md | 31 ++++++++++++++++++ 3 files changed, 123 insertions(+) create mode 100644 bench/docs/contribution_guidelines.md create mode 100644 bench/docs/release_policy.md create mode 100644 bench/docs/releasing_frappe_erpext.md diff --git a/bench/docs/contribution_guidelines.md b/bench/docs/contribution_guidelines.md new file mode 100644 index 00000000..9d6ba368 --- /dev/null +++ b/bench/docs/contribution_guidelines.md @@ -0,0 +1,46 @@ +# Contribution Guidelines + +### Introduction (for first timers) + +Thank you for your interesting in contributing to an open source project! Our world works on people taking initiative to contribute to the "commons" and contributing to open source means you are contributing to make things better for not only yourself, but everyone else too! So thank you for taking this initiative. + +Great projects also work because of great quality. Open source or not, the user really cares that things should work as they are advertised, and consistently. New features should follow the same pattern and so that users don't have to learn things again and again. + +Developers who maintain open source also expect that you follow certain guidelines. These guidelines ensure that developers are able quickly give feedback on your contribution and how to make it better. Most probably you might have to go back and change a few things, but it will be in th interest of making this process better for everyone. So do be prepared for some back and forth. + +Happy contributing! + +### Feedback Policy + +We will strive for a "Zero Pull Request Pending" policy, inspired by "Zero Inbox". This means, that if the pull request is good, it will be merged within a day and if it does not meet the requirements, it will be closed. + +### Design Guides + +Please read the following design guidelines carefully when contributing: + +1. [Form Design Guidelines](https://github.com/frappe/erpnext/wiki/Form-Design-Guidelines) +1. [How to break large contributions into smaller ones](https://github.com/frappe/erpnext/wiki/Cascading-Pull-Requests) + +### Pull Request Requirements + +1. **Test Cases:** Important to add test cases, even if its a very simple one that just calls the function. For UI, till we don't have Selenium testing setup, we need to see a screenshot / animated GIF. +1. **UX:** If your change involves user experience, add a screenshot / narration / animated GIF. +1. **Documentation:** Test Case must involve updating necessary documentation +1. **Explanation:** Include explanation if there is a design change, explain the use case and why this suggested change is better. If you are including a new library or replacing one, please give sufficient reference of why the suggested library is better. +1. **Demo:** Remember to update the demo script so that data related your feature is included in the demo. +1. **Failing Tests:** This is simple, you must make sure all automated tests are passing. +1. **Very Large Contribution:** It is very hard to accept and merge very large contributions, because there are too many lines of code to check and its implications can be large and unexpected. They way to contribute big features is to build them part by part. We can understand there are exceptions, but in most cases try and keep your pull-request to **30 lines of code** excluding tests and config files. **Use [Cascading Pull Requests](https://github.com/frappe/erpnext/wiki/Cascading-Pull-Requests)** for large features. +1. **Incomplete Contributions must be hidden:** If the contribution is WIP or incomplete - which will most likely be the case, you can send small PRs as long as the user is not exposed to unfinished functionality. This will ensure that your code does not have build or other collateral issues. But these features must remain completely hidden to the user. +1. **Incorrect Patches:** If your design involves schema change and you must include patches that update the data as per your new schema. +1. **Incorrect Naming:** The naming of variables, models, fields etc must be consistent as per the existing design and semantics used in the system. +1. **Translated Strings:** All user facing strings / text must be wrapped in the `__("")` function in javascript and `_("")` function in Python, so that it is shown as translated to the user. +1. **Deprecated API:** The API used in the pull request must be the latest recommended methods and usage of globals like `cur_frm` must be avoided. +1. **Whitespace and indentation:** The ERPNext and Frappe Project uses tabs (I know and we are sorry, but its too much effort to change it now and we don't want to lose the history). The indentation must be consistent whether you are writing Javascript or Python. Multi-line strings or expressions must also be consistently indented, not hanging like a bee hive at the end of the line. We just think the code looks a lot more stable that way. + +#### What if my Pull Request is closed? + +Don't worry, fix the problem and re-open it! + +#### Why do we follow this policy? + +This is because ERPNext is at a stage where it is being used by thousands of companies and introducing breaking changes can be harmful for everyone. Also we do not want to stop the speed of contributions and the best way to encourage contributors is to give fast feedback. \ No newline at end of file diff --git a/bench/docs/release_policy.md b/bench/docs/release_policy.md new file mode 100644 index 00000000..73cb4462 --- /dev/null +++ b/bench/docs/release_policy.md @@ -0,0 +1,46 @@ +# Release Policy + +We maintain a **staging** branch for erpnext and frappe. On every Wednesday, release team will create a **staging** branch from **develop** (Internal Release). Same on every Tuesday,we will release from **staging** branch to **master** (Community Release). We also maintain **hotfix** branch, to fix bugs from release. Hot fixes release will take place as per the priority and severity. + + +**I. Branch Description** + +1. develop: All new feature developments will go in develop branch +2. staging: This branch serves as a release candidate. Before a week, release team will pull feature from develop branch to staging branch.
EG: if feature is in 25 July's milestone then it should go in staging on 19th July. +3. master: Community release. +4. hotfix: mainly define for support issues. This will include bugs or any high priority task like security patches. + + +**II. Where to send PR?** + +1. If you are working on a new feature, then PR should point to develop branch +2. If you are working on support issue / bug / error report, then PR should point to hotfix brach +3. While performing testing on Staging branch, if any fix needed then only send that fix PR to staging. +4. Direct push to master strictly prohibited. + + +**III. Versioning** + +1. develop to staging: No release number, cherry-pick or hard push from develop. +2. staging to master: + Patch: Small fixes + Minor: For new features updates. + Major: If any API changes +3. hotfix to master: Patch version release + + +**IV. Release Impact on branches:** + +1. Releasing from staging: + staging -> master -> develop -> hotfix +2. Releasing from hotfix: + hotfix -> master -> develop -> staging + + +**V. Servers/Sites and Branches:** + +1. Frappe Cloud: master branch (Every Tuesday) +2. Frappe.io and Central: staging Branch (Every Wednesday) +3. demo.erpnext.com: master +4. beta.erpnext.com: staging + diff --git a/bench/docs/releasing_frappe_erpext.md b/bench/docs/releasing_frappe_erpext.md new file mode 100644 index 00000000..d9e134d3 --- /dev/null +++ b/bench/docs/releasing_frappe_erpext.md @@ -0,0 +1,31 @@ +# Releasing Frappe ERPNext + +* Make a new bench dedicated for releasing +``` +bench init release-bench --frappe-path git@github.com:frappe/frappe.git +``` + +* Get ERPNext in the release bench +``` +bench get-app erpnext git@github.com:frappe/erpnext.git +``` + +* Configure as release bench. Add this to the common_site_config.json +``` +"release_bench": true, +``` + +* Use the release commands to release +``` +Usage: bench release [OPTIONS] APP BUMP_TYPE +``` + +* Arguments : + * _APP_ App name e.g [frappe|erpnext|yourapp] + * _BUMP_TYPE_ [major|minor|patch|stable|prerelease] +* Options: + * --develop git develop branch, default is develop + * --master git master branch, default is master + * --remote git remote, default is upstream + * --owner git owner, default is frappe + * --repo-name git repo name if different from app name \ No newline at end of file