[asterisk-dev] GitHub: Proposed Pull Request Process

[George Joseph]

I think publishing this on the dev list before the wiki will make it easier
for people to read, quote and respond,so here goes...

Since most of you have used GitHub, the first part of this process should
be familiar.   Before we get into it though, you should install the GitHub
CLI (gh).  Most distributions have a package for it.  Although not strictly
required, it'll make life easier.

I'm using "asterisk" as the example but the same applies to the "testsuite"
repo as well.

   1. Fork the asterisk/asterisk repo into your own account.
   2. Clone the forked repo to your local dev environment:
   `gh repo clone you/asterisk`
   The gh tool will automatically create an "upstream" remote that
   points back to asterisk/asterisk as well as the "origin" remote pointing to
   your fork.
   3. Set the default remote repository:
   `gh repo set-default`
   When prompted, select "asterisk/asterisk" which should be the default
   choice.
   4. Checkout a branch, do some work and commit as usual.  I'll use
   "master" as an example.  We've got some additional commit message
   formatting rules that do away with the need to create entries in the
   doc/CHANGES-staging and doc/UPGRADE-staging directories.  More on this
   later.
   5. Create a pull request with:
   `gh pr create --fill --base master`
   Do NOT cherry-pick to any other branches at this time.
   6. When you submit your first pull request, you'll need to open the PR
   in a browser, scroll down to the checks area, click the "details" link for
   the "license/cla" entry and complete a new license agreement.

At this point, things become a bit "special" because of the way GitHub
operates and the fact that we maintain multiple simultaneous release
branches.

Testing:

With Gerrit, when you submit a new review, the unit tests run but the gate
tests don't run until we do a '+2'.  With the new process, we have more
resources at our disposal so we run both the unit and gate tests
immediately.  You'll notice a whole bunch of entries in the PR checks area
for them and you can easily click through to see the details.  Right now,
the output is overly verbose but we'll pare that down over time.

Addressing test failures or review feedback:

I'll cover the actual review process later but if you need to make changes,
the process will be much like it is today (at first).  While Gerrit has a
one-to-one relationship between commit and review, GitHub allows a PR to
contain multiple commits.  For the time being though, we'd like to keep the
one-to-one relationship to keep things simple.  This means making your
changes locally and doing a `git commit --amend` as you do today but then
doing a `git push --force` to update the PR instead of a `git review`.
There's one exception to this rule though.  See below.

Cherry-picking:

This is where things really get "special".  If you've worked with GitHub
you know that, unlike Gerrit, they have no built-in support for
cherry-picking but we've come with a way to automate most of the process:

   1. Once your PR is created, simply add a comment indicating which other
   branches you'd like the PR cherry-picked to.  If the PR was submitted
   against the master branch and you'd like it cherry-picked to the 18 and 20
   branches, you'd add a comment as follows:
   Comment:
   cherry-pick-to: 18
   cherry-pick-to: 20
   2. When you get your first "+1" review, a core team member will add a
   label to the PR that will trigger test cherry-picks to the branches you
   indicated and run the unit and gate tests on each.
   3. If there are no merge conflicts or test failures then when the base
   PR merges, the cherry-picks will automatically merge to their respective
   branches.
   4. If code changes are required for a specific branch, you'll need to
   edit the comment listing the cherry-pick branches and remove the offending
   entry, then submit a completely separate PR for that branch.

The exception to the one-to-one rule:

When you have a series of patches that depend on each other, Gerrit detects
this and only creates new reviews for the new commits and uses the earlier
in-progress reviews as the base for them.  GitHub does things a bit
different depending on how you push up the new work.  If you create a new
commit in the same branch as the first one and do a simple `git push`, the
new commit will be added to the existing PR.  If you instead do a `gh pr
create`, a new PR will be created that has both the new and earlier
commits.  This can make things a bit confusing and we're not quite sure how
to deal with it yet.  Stay tuned.

Comments?  Questions?  Despite everything written above, I think that for
the majority of contributions, the GitHub process will actually be easier
than the current Gerrit process.

--
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20230404/e4c2e7c7/attachment.html>