devnotes: address feedback from docs@ thread Add committer setup steps (SSH key, GitBox account linking), show three ways to work on trunk and 2.4.x (two clones, switching, worktrees), and add a worked example of making the same change on both branches. Drop the stale 2.4.1 module compatibility sentence and note that the CTR workflow under pull requests is not yet decided.
diff --git a/content/dev/devnotes.md b/content/dev/devnotes.md index 854a092..5e699b7 100644 --- a/content/dev/devnotes.md +++ b/content/dev/devnotes.md
@@ -12,48 +12,163 @@ <https://github.com/apache/httpd>. The repository used to live in Subversion, and the old SVN tree is no longer used for new work. -There are two active branches: +There are two active branches, both in the same repository: * <samp>trunk</samp> is the development branch (2.5, slated for a 2.6 release). * <samp>2.4.x</samp> is the current stable branch. -To get a copy of the source: +# Committer Setup # - % git clone https://github.com/apache/httpd.git +Committers need to do the following once before they can push to the +repository. + +1. Create an SSH key, if you do not already have one: + + % ssh-keygen -t ed25519 -C "you@example.org" + % ssh-add ~/.ssh/id_ed25519 + +1. Add the key to your GitHub account. On GitHub, open your profile, then + Settings, then SSH and GPG keys, and click New SSH key. Give the key a + name and paste the contents of <samp>~/.ssh/id_ed25519.pub</samp> into + the Key field. + +1. Link your GitHub account to your ASF account. The steps are described + on the [Apache GitHub](https://infra.apache.org/apache-github.html) page, + which takes you to [GitBox](https://gitbox.apache.org/boxer/). Follow the + instructions there. + +1. Wait for an email saying that you have been added to the "Apache + Committers" team. You can push to the repository once that arrives. + +Non-committers do not need any of this. Fork +<https://github.com/apache/httpd> on GitHub instead, and use your fork's +URL in place of the one below. + +# Getting the Source # + +Committers should clone using the SSH URL, +<samp>git@github.com:apache/httpd.git</samp>. If you only want to read the +code, <samp>https://github.com/apache/httpd.git</samp> works without any +setup. + +Since <samp>trunk</samp> and <samp>2.4.x</samp> live in one repository, +there are a few ways to work on both. Pick whichever suits you. + +## Two clones ## + +This is the closest to the old SVN layout, with one directory per branch: + + % git clone git@github.com:apache/httpd.git httpd-trunk + % git clone -b 2.4.x git@github.com:apache/httpd.git httpd-2.4.x + +The <samp>-b 2.4.x</samp> option picks the branch to check out. Each +directory then behaves like its own SVN checkout. + +## One clone, switching branches ## + +Keep a single directory and change which branch it shows: + + % git clone git@github.com:apache/httpd.git httpd % cd httpd - -This gives you <samp>trunk</samp>. To work on the stable branch instead: - % git switch 2.4.x + % git switch trunk -The developers continue to seek to maintain module compatibility between -2.4.1 and future 2.4 releases for administrators and end users. +Commit or stash any changes before you switch, or git will refuse to +switch (or carry the changes with you). + +## Worktrees ## + +A worktree gives you a second directory for another branch, sharing one +clone: + + % git clone git@github.com:apache/httpd.git httpd-trunk + % cd httpd-trunk + % git worktree add ../httpd-2.4.x 2.4.x + +This looks like the two clones layout, but both directories share the +same history, so a commit made in one is visible in the other straight +away. # Making Changes # All changes go through pull requests on GitHub, for both -<samp>trunk</samp> and <samp>2.4.x</samp>. +<samp>trunk</samp> and <samp>2.4.x</samp>. A change that is needed on both +branches gets one pull request for each. -1. Fork <https://github.com/apache/httpd> on GitHub and clone your fork. +Please follow the Apache style, as described in the +[style guide](styleguide.html). Larger changes or new features are worth +raising on the [developers list](https://httpd.apache.org/lists.html#http-dev) +before you spend a lot of time on them. -1. Create a branch for your change from the branch you are targeting: +## Example ## - % git switch -c my-fix trunk +Say you have updated <samp>docs/manual/bind.xml.fr</samp> and the change is +needed on both branches. Using the two clones layout: -1. Make your changes and check that they build and pass the tests. Please - follow the Apache style, as described in the [style guide](styleguide.html). +1. Bring trunk up to date and create a branch for the change: -1. Commit, push the branch to your fork, and open a pull request against - <samp>trunk</samp> or <samp>2.4.x</samp> in the - [httpd repository](https://github.com/apache/httpd/pulls). + % cd httpd-trunk + % git switch trunk + % git pull + % git switch -c bind-fr-update -Keep your branch up to date with the upstream branch while the pull request -is open, as reviewers may ask for changes before it can be merged. +1. Edit the file, then commit it: -Larger changes or new features are worth raising on the -[developers list](https://httpd.apache.org/lists.html#http-dev) before you -spend a lot of time on them. + % git add docs/manual/bind.xml.fr + % git commit -m "Update French translation of bind.xml" + +1. Push the branch to GitHub: + + % git push origin bind-fr-update + + The output includes a link to create a pull request. Open it, check that + the base branch is <samp>trunk</samp>, and create the pull request. You + can also start one from the + [pull requests](https://github.com/apache/httpd/pulls) page. + +1. Do the same in the 2.4.x directory, with a branch of its own: + + % cd ../httpd-2.4.x + % git switch 2.4.x + % git pull + % git switch -c bind-fr-update-2.4 + + Either make the same edit by hand and commit it as above, or copy the + trunk commit across with <samp>git cherry-pick</samp>: + + % git fetch origin bind-fr-update + % git cherry-pick FETCH_HEAD + + If the file differs between the branches, the cherry-pick may stop with + a conflict. Run <samp>git cherry-pick --abort</samp> and make the edit by + hand instead. + +1. Push the 2.4.x branch and open a second pull request, this time with + <samp>2.4.x</samp> as the base branch: + + % git push origin bind-fr-update-2.4 + +1. Once the pull requests have been merged, tidy up: + + % git switch 2.4.x + % git pull + % git branch -D bind-fr-update-2.4 + % git push origin --delete bind-fr-update-2.4 + + and the same for <samp>bind-fr-update</samp> in the trunk directory. + +With a single clone, run all of the steps in the same directory and use +<samp>git switch</samp> to move between branches. The cherry-pick step +becomes <samp>git cherry-pick bind-fr-update</samp>, as the trunk commit is +already in your clone. The same goes for worktrees, where you just change +directory instead of switching. + +Non-committers push to their fork instead of <samp>origin</samp>, and open +the pull request from there. + +If a reviewer asks for changes, commit them to the same branch and push +again. The pull request updates automatically. # Review and Backports # @@ -66,12 +181,12 @@ against <samp>2.4.x</samp>. The approvals that used to be recorded as votes in STATUS are now given as reviews on that pull request. -# Committer Access # - -Committers need to link their ASF and GitHub accounts before they can push -to or merge in the repository. This is done through the ASF -[GitBox account linking](https://gitbox.apache.org/setup/) page, which also -requires two-factor authentication to be enabled on your GitHub account. +**Not yet decided:** how commit-then-review changes, such as documentation +and translation updates on trunk, work with pull requests. For example, +whether committers can merge their own pull request without a review. Until +this is settled, ask on the +[developers list](https://httpd.apache.org/lists.html#http-dev) if you are +unsure. # Other Repositories #