Official documentation about "Gerrit Change Number"

leeyuiwah Source

This is a follow-up question of my other question: What is the official name of the number in a Gerrit review url

I have now learned that the small integer embedded in a Gerrit url is called "Gerrit Change Number" and sometimes "Numeric Change Number". For example, it is the number 68 in the following Gerrit url

http://gerrithost:8080/68

This number plays an important role in understand the Gerrit workflow, yet there are not a lot of discussion about it. I even have a feeling that it may have been deprecated (because a Change-Id -- the long hash string prefixed with the character "I" -- also uniquely identify a gerrit Change)

Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b

Where can I find more discussion about Gerrit Change Number? Is it indeed deprecated? If it is, then does that mean there is a workflow that does not use the numeric number? (But how would the Gerrit URL be constructed?)

I found this discussion on this page (Gerrit User Guide). It indicates the importance of the number in the workflow.

When a commit is pushed for review, Gerrit stores it in a staging area which is a branch in the special refs/changes/ namespace. A change ref has the format refs/changes/XX/YYYY/ZZ where YYYY is the numeric change number, ZZ is the patch set number and XX is the last two digits of the numeric change number, e.g. refs/changes/20/884120/1. Understanding the format of this ref is not required for working with Gerrit.

gitgerrit

Answers

answered 6 months ago Marcelo Ávila de Oliveira #1

The Gerrit change number is not deprecated. It's the way to access the Gerrit changes in the browser URL (https://GERRIT-SERVER/GERRIT-CHANGE-NUMBER).

The Change-Id identify changes too but it was created later to address an specific issue: identify commits (patchsets) that belong to the same review. For instance, when a change needs to be modified, a second commit can be uploaded to address the reported issues. Gerrit allows attaching those 2 commits to the same change, and relies upon a Change-Id line at the bottom of a commit message to do so. With this Change-Id, Gerrit can automatically associate a new version of a change back to its original review, even across cherry-picks and rebases.

Learn more about the Change-Id here.

answered 6 months ago Schwern #2

Change Number and Change-ID serve different purposes.

From the Gerrit Docs on Change-Ids...

Gerrit needs to identify commits that belong to the same review. For instance, when a change needs to be modified, a second commit can be uploaded to address the reported issues. Gerrit allows attaching those 2 commits to the same change, and relies upon a Change-Id line at the bottom of a commit message to do so. With this Change-Id, Gerrit can automatically associate a new version of a change back to its original review, even across cherry-picks and rebases.

The Change-ID is a checksum used to identify the same change across rebases, amends, and other ways to rewrite commits in the course of review. Here's the key thing: Git does not rewrite commits. Git creates new commits and pretends it was that way all along. Gerrit needs a way to know that these new commits are, in fact, related to the ones you put up for review.

More from the User Guide...

If a commit that has a Change-Id in its commit message is pushed for review, Gerrit checks if a change with this Change-Id already exists for this project and target branch, and if yes, Gerrit creates a new patch set for this change. If not, a new change with the given Change-Id is created.

If a commit without Change-Id is pushed for review, Gerrit creates a new change and generates a Change-Id for it.

Amending and rebasing a commit preserves the Change-Id so that the new commit automatically becomes a new patch set of the existing change, when it is pushed for review.

One way to look at it is the Change Number is the human readable identifier for a Change. The Change-ID is bookkeeping for Gerrit. The Change-ID is only visible to the user because Git has no way for Gerrit to store metadata about a commit other than putting it in the commit message.

answered 6 months ago ElpieKay #3

The change number uniquely identifies a change. It's a unique value of a change entry. Besides the urls and refs, it can be used in Gerrit query and REST APIs.

ssh -p 29418 [email protected]$gerrithost gerrit query change:884120
curl --digest --user $user:$httpassword $gerrithost/gerrit/a/changes/884120

answered 6 months ago leeyuiwah #4

I was expecting some discussion like this. I believe the following assertions are true, but I need confirmations. (That was why I was looking for documentation in the first place). Please help me.

  1. A Gerrit Change Number (aka Numeric Change Number), like Gerrit Change-Id, uniquely identifies a "change under review", which may have multiple patch sets as often are needed in a code-review cycle. Unlike Gerrit Change-Id, it is a small integer and perhaps more easy to use for human users. (In contrast, Gerrit Change-Id is a long hash string preceded with the character "I")
  2. A Gerrit Change Number is used in refs (see the section cited in the opening question) and in URLs and query and REST APIs (see the answer of ElpieKay)
  3. A Gerrit Change Number is unique to a server. Multiple projects hosted on the same server shares the same number space.
  4. A Gerrit Change Number is typically generated monotonically increasing as new changes are submitted for review to a Gerrit server. Note, however, that since different changes may take different time to finish code review, there is no guarantee that the changes will be applied to the master branch in order (or be applied at all). As such it is possible to have a change with a larger numeric change number Y to take effect on the master branch before another change with a smaller numeric change number X. In other words, on the master branch, when there are two changes with numbers X and Y respectively, and X<Y, there is NO guarantee that X happens-before Y.

comments powered by Disqus