| = Gerrit Code Review - Development Processes |
| |
| [[contribution-process]] |
| == Contribution Process |
| |
| See link:dev-contributing.html[here]. |
| |
| [[dev-in-stable-branches]] |
| == Development in stable branches |
| |
| As their name suggests stable branches are intended to be stable. This means that generally |
| only bug-fixes should be done on stable branches, however this is not strictly enforced and |
| exceptions may apply: |
| |
| * When a stable branch is initially created to prepare a new release the Gerrit community |
| discusses on the mailing list if there are pending features which should still make it into the |
| release. Those features are blocking the release and should be implemented on the stable |
| branch before the first release candidate is created. |
| * To stabilize the code before doing a major release several release candidates are created. Once |
| the first release candidate was done no more features should be accepted on the stable branch. |
| If more features are found to be required they should be discussed with the Gerrit maintainers |
| and should only be allowed if the risk of breaking things is considered to be low. |
| * Once a major release is done only bug-fixes and documentation updates should be done on the |
| stable branch. These updates will be included in the next minor release. |
| * For minor releases new features are only acceptable if they are important to the Gerrit |
| community, if they are backwards compatible and the risk of breaking things is low and if there |
| are no objections from the Gerrit community. |
| * In cases of doubt it's the responsibility of the release maintainer to evaluate the risk of new |
| features and make a decision based on these rules and opinions from the Gerrit community. |
| * The older a stable branch is the more stable it should be. This means old stable branches |
| should only receive bug-fixes that are either important or low risk. Security fixes, including |
| security updates for third party dependencies, are always considered as important and hence can |
| always be done on stable branches. |
| |
| [[backporting]] |
| == Backporting to stable branches |
| |
| From time to time bug fix releases are made for existing stable branches. |
| |
| Developers concerned with stable branches are encouraged to backport or push fixes to these |
| branches, even if no new release is planned. Backporting features is only possible in compliance |
| with the rules link:#dev-in-stable-branches[above]. |
| |
| Fixes that are known to be needed for a particular release should be pushed for review on that |
| release's stable branch. They will then be included into the master branch when the stable branch |
| is merged back. |
| |
| [[upgrading-libraries]] |
| == Upgrading Libraries |
| |
| Changes that add new libraries or upgrade existing libraries require an approval on the |
| `Library-Compliance` label. For an approval the following things are checked: |
| |
| * The library has a license that is suitable for use within Gerrit. |
| * If the library is used within Google, the version of the library must be compatible with the |
| version that is used at Google. |
| |
| Only maintainers from Google can vote on the `Library-Compliance` label. |
| |
| Gerrit's library dependencies should only be upgraded if the new version contains |
| something we need in Gerrit. This includes new features, API changes as well as bug |
| or security fixes. |
| An exception to this rule is that right after a new Gerrit release was branched |
| off, all libraries should be upgraded to the latest version to prevent Gerrit |
| from falling behind. Doing those upgrades should conclude at the latest two |
| months after the branch was cut. This should happen on the master branch to ensure |
| that they are vetted long enough before they go into a release and we can be sure |
| that the update doesn't introduce a regression. |
| |
| [[deprecating-features]] |
| == Deprecating features |
| |
| Gerrit should be as stable as possible and we aim to add only features that last. |
| However, sometimes we are required to deprecate and remove features to be able |
| to move forward with the project and keep the code-base clean. The following process |
| should serve as a guideline on how to deprecate functionality in Gerrit. Its purpose |
| is that we have a structured process for deprecation that users, administrators and |
| developers can agree and rely on. |
| |
| General process: |
| |
| * Make sure that the feature (e.g. a field on the API) is not needed anymore or blocks |
| further development or improvement. If in doubt, consult the mailing list. |
| * If you can provide a schema migration that moves users to a comparable feature, do |
| so and stop here. |
| * Mark the feature as deprecated in the documentation and release notes. |
| * If possible, mark the feature deprecated in any user-visible interface. For example, |
| if you are deprecating a Git push option, add a message to the Git response if |
| the user provided the option informing them about deprecation. |
| * Annotate the code with `@Deprecated` and `@RemoveAfter(x.xx)` if applicable. |
| Alternatively, use `// DEPRECATED, remove after x.xx` (where x.xx is the version |
| number that has to be branched off before removing the feature) |
| * Gate the feature behind a config that is off by default (forcing admins to turn |
| the deprecated feature on explicitly). |
| * After the next release was branched off, remove any code that backed the feature. |
| |
| You can optionally consult the mailing list to ask if there are users of the feature you |
| wish to deprecate. If there are no major users, you can remove the feature without |
| following this process and without the grace period of one release. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |