errose28 commented on code in PR #463: URL: https://github.com/apache/ozone-site/pull/463#discussion_r3417313934
########## docs/08-developer-guide/04-project/01-git/03-feature-branches/01-overview.md: ########## @@ -0,0 +1,42 @@ +--- +sidebar_label: Overview +--- + +# Feature Branches + +Feature branches are used for larger or longer-running work that would be hard to land incrementally on `master` without destabilizing it. Feature branches are often named after the Jira epic tracking the work and an abbreviated feature name, for example `HDDS-3816-ec` or `HDDS-10611-mpu`. You can see all the Ozone repo's branches [here](https://github.com/apache/ozone/branches). Most incremental changes do not require feature branches and can go directly to `master` as a pull request as documented in [`CONTRIBUTING.md`](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md). + +## When to use a feature branch + +Use a feature branch for changes that: +- Make iterative changes to core code paths. +- Require broader community testing. +- Cannot be easily gated with a feature flag. + - The covers changaes that migrate existing code paths instead of adding completely new ones. +- Would have issues if a release was cut in the middle of their development. + - A release branch can be cut from `master` at any time and feature development should not block this. + - If a feature has upgrade compatibility concerns that will not be addressed right away, it should be developed on a feature branch. + - Note that protobuf messages and wire protocols become locked into compatability guarantees once they are released. + - If a feature is making changes in this area and it wants to keep the structure flexible while it is being finalized, it should be done on a feature branch. + + +## Merge Process + +Complete the following steps when a feature branch is ready to be merged into `master`: + +1. Complete the [branch merge checklist](./merge-checklist) for your feature branch and raise it as a pull request to the [ozone-site](https://github.com/apache/ozone-site) repo's `master` branch. + + - Feature branch merge checklists will be committed [to the website](./merged-branches) once the branch merge is approved. + +2. Start a mail thread on the `[email protected]` mailing list for committers and PMC members to vote on the branch merge. Include a link to the branch merge checklist PR. + +3. If the vote passes, changes from the feature branch will be incorporated into `master`, and development can continue on the `master` branch. + +**Do not use GitHub "Squash and merge" or rebase** to land the feature branch onto `master`. Use a **regular `git merge`** so history, Jira links, and PR discussions stay aligned with the original commit IDs. Review Comment: We need to decide what our actual guidelines are for: 1. Updating feature branches with changes from master incrementally 2. Incorporating the feature branch back into master We want to avoid using merge for 1 and 2, because the layers of merge commits become difficult to follow when tracking the git history. One option is using rebase to bring the commits into master. That will erase any merge commits on the branch so devs are free to use either rebase or merge to update their feature branch from master while working. Another option is to rebase the feature branch and then merge it to master. This way master doesn't need to stay frozen while the feature branch rebase is happening. We may want to force a merge commit in this case even if it is not necessary for consistency across feature branch merges. If there is another way to scrub the incremental merge commits before merging to master we could use that as well. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
