HDDS-15566. Move feature branch merge checklist to the website

cspell.yaml

@@ -217,6 +217,9 @@ words:
 - minimising
 - tarballed
 - Namenodes
+- WIP
+- smoketest
+- microbenchmark
 # Apache Ozone community member names
 - Sumit
 # Company names for "Who Uses Ozone" page

docs/08-developer-guide/04-project/01-git/01-overview.md

@@ -0,0 +1,28 @@
+---
+sidebar_label: Overview
+---
+
+# Git Branches and Tags
+
+The [Apache Ozone](https://github.com/apache/ozone) codebase on GitHub uses a small number of **long-lived branch patterns**, many **short-lived Jira-named branches**, and **signed tags** for releases. This section covers how they fit together for contributors and release managers.
+
+:::info Product repo versus this website
+
+Branch and tag names below refer to **[`apache/ozone`](https://github.com/apache/ozone)**. The documentation site you are reading is **[`apache/ozone-site`](https://github.com/apache/ozone-site)** and follows its own branching (for example `master` and `asf-site` for publishing).
+
+:::
+
+## The `master` branch
+
+Day-to-day development targets **`master`** in [`apache/ozone`](https://github.com/apache/ozone). Pull requests from forks are usually opened against `master`, and GitHub Actions CI ([`build-branch`](https://github.com/apache/ozone/blob/master/.github/workflows/post-commit.yml)) validates proposed changes.
+
+The community tries to keep **`master` in a releasable state**: it should build, tests should be in good shape, and risky work should not land without review and appropriate checks. That expectation is why large or disruptive efforts are often done on **feature branches** and merged only after broader validation.
+
+For routine contribution steps (fork, branch, PR, Jira), see [Ozone `CONTRIBUTING.md`](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md).
+
+## See also
+
+- [Ozone `CONTRIBUTING.md`](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md) — everyday PR workflow to `master`
+- [`.github/ci.md`](https://github.com/apache/ozone/blob/master/.github/ci.md) — what CI runs on branches and PRs
+- [Release Manager Guide](../release-guide) — step-by-step release process
+

docs/08-developer-guide/04-project/01-git/02-release-branches.md

@@ -0,0 +1,30 @@
+---
+sidebar_label: Release Branches
+---
+
+# Release Branches and Tags
+
+## Release branches
+
+When the project prepares a **minor** (or major) release, maintainers cut a **release branch** from an agreed point on `master`. The naming pattern is:
+
+`ozone-<major>.<minor>`
+
+Examples: `ozone-2.0`, `ozone-2.1`. **Patch** releases for that line (for example 2.0.1) are typically produced from the same branch. Details — `proto.lock` updates, bumping the SNAPSHOT on `master`, tagging — are in the [release manager guide](../release-guide).
+
+Release branches are **not** where general feature development happens; fixes that belong in the release are cherry-picked or landed on the release branch as described in that guide.
+
+## Tags
+
+Ozone uses **annotated Git tags** on [`apache/ozone`](https://github.com/apache/ozone) to mark release candidates and final releases. You will see names such as:
+
+- **`ozone-2.1.0`**, **`ozone-2.0.0`** — final release tags
+- **`ozone-2.1.0-RC0`**, **`ozone-2.1.0-RC1`**, … — release candidate tags
+
+Tags appear on the [Tags](https://github.com/apache/ozone/tags) page and drive [GitHub Releases](https://github.com/apache/ozone/releases). Creating and pushing the final tag is part of the release process in the [release manager guide](../release-guide).
+
+## See also
+
+- [Release Manager Guide](../release-guide) — step-by-step release process, RC tags, and publishing
+- [Feature branches](./feature-branches) — feature branch lifecycle and merge process
+- [Ozone `CONTRIBUTING.md`](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md) — everyday PR workflow to `master`

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 changes 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 compatibility 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 `dev@ozone.apache.org` 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.
+
+## See also
+
+- [Release branches](../release-branches) — release branch lifecycle and tags
+- [Release Manager Guide](../../release-guide) — RC tags and publishing
+- [Ozone `CONTRIBUTING.md`](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md) — everyday PR workflow to `master`
+

docs/08-developer-guide/04-project/01-git/03-feature-branches/02-merge-checklist.md

@@ -0,0 +1,97 @@
+# Feature Branch Merge Checklist
+
+This section collects generic questions which can be checked for each feature branch. Some of them are obvious for some branches (for example: the decommissioning feature didn't change the s3 interface) but it's good to go through them for each of the merges. Answering these questions will also help the community to test the branch. If you have any new idea about what should be checked, submit a pull request to the [ozone-site](https://github.com/apache/ozone-site) repo to update this page.
+
+## Summary
+
+Include a brief summary of the feature, and fill in the following information:
+
+- Branch name: `<feature branch to be merged>`
+- Jira: `<Jira epic tracking all subtasks of the feature>`
+- Commit: `<Git hash of the commit at the tip of the branch that will be merged>`
+
+## Stable Builds
+
+To keep the master branch stable, it's recommended to run the full CI build 3-5 times on the latest commit proposed to be merged. Any failure should be analyzed and checked against previous failures on master to see if it is related to the branch.
+
+All CI runs for the feature branch can be checked at `github.com/apache/ozone/actions?query=<BRANCH_NAME>`.
+
+## User Documentation
+
+Adding user documentation before the merge will help the community test and evaluate the feature. User documentation should be added to this website with a pull request to the [ozone-site](https://github.com/apache/ozone-site) repo. Note that the documentation will be listed under the `next` version section until it is included in a release.
+
+## Developer Documentation
+
+If the feature required a design document, ensure its PR is approved and it has been committed under the main Ozone repo's `hadoop-hdds/docs/content/design/` directory so it is preserved in the source history.
+
+## S3 Compatibility
+
+Explain how any S3 API behavior changes with the addition of this feature.
+
+## Docker Compose and Acceptance Tests
+
+Verify that Docker-compose clusters still start correctly. Add or update Robot Framework acceptance tests in `hadoop-ozone/dist/src/main/compose` to cover the new feature's behavior and allow other developers to test it in a local environment.
+
+## Containers and Kubernetes
+
+If the feature affects cluster topology, configuration, or runtime behavior, update the Kubernetes example manifests under `hadoop-ozone/dist/src/main/k8s`.
+
+## Code Coverage and Quality
+
+Review the [SonarCloud](https://sonarcloud.io/project/overview?id=apache_ozone) metrics for the branch and compare them against `master`. Regressions in coverage, duplications, or code smells should be addressed before merge.
+
+## Build Time
+
+The ASF uses a shared pool of Github Actions CI minutes for all projects, so we should avoid significant increase of the build time unless it's fully necessary. Compare the end-to-end CI build duration of the feature branch against `master`. Flag significant regressions so the community can decide whether they are acceptable.
+
+All Github actions runs for a branch can be found at `github.com/apache/ozone/actions?query=<BRANCH_NAME>`.
+
+## Incompatible Changes
+
+Ozone currently supports non-rolling upgrades and downgrades even when backwards incompatible features are present. Backwards incompatible features should be added to the versioning framework so that they are not used until the Ozone upgrade is finalized, after which downgrading is not possible.
+
+Client cross compatibility should also be maintained as much as possible, with sensible error messages provided when this is not possible. An old client should be able to talk to the new Ozone instance, and a new client should be able to talk to the old Ozone instance.
+
+## Third Party Dependencies or License Changes
+
+Diff the distribution tar files to identify any new or updated third-party libraries. For each new library, update `LICENSE` and `NOTICE` in the appropriate module so the release artifacts remain license-compliant.
+
+The easiest way to check this is by building Ozone from the feature branch and from master, then comparing the files between them:
+
+```shell
+git checkout origin/master
+mvn clean install -DskipTests
+cd hadoop-ozone/dist/target/ozone-*/
+find -type f | sort > /tmp/master
+
+git checkout origin/$BRANCH_NAME
+mvn clean install -DskipTests
+cd hadoop-ozone/dist/target/ozone-*/
+find -type f | sort > /tmp/$BRANCH_NAME
+
+git diff /tmp/$BRANCH_NAME /tmp/master
+```
+
+## Performance
+
+Share `ozone freon` benchmark results that demonstrate the performance impact of the feature. Include baseline numbers from `master` so the community can evaluate the delta. Feature branches should not introduce performance regressions, but in some cases they may improve performance.
+
+## Security Considerations
+
+Document any new attack surfaces, privilege changes, or cryptography decisions. Pay particular attention to input validation for features that add network-accessible endpoints or handle user-supplied data.
+
+## Configuration Changes
+
+Document any new configuration keys added or existing configurations whose defaults were changed by this feature and what their impact will be.
+
+## Dangling TODO Comments
+
+`TODO` comments are often left in the code when working on a feature branch for ideas that need to be worked out later or were split into smaller PRs. If there are new `TODO` comments introduced by the branch, ensure that the comment also contains the ID of an open Jira which will resolve it and document this existing gap. For example:
+
+```java
+// TODO HDDS-1234: Finalize the return type of this method.
+```
+
+There should be no new `TODO`s that do not contain references to open Jiras.
+
+To see all TODOs unique to your branch from `master`, check out your feature branch and run `git diff master... | grep -i todo`.