Official documentation about “Gerrit Change Number”

Question

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

Answer 1

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.

Answer 2

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 $user@$gerrithost gerrit query change:884120
curl --digest --user $user:$httpassword $gerrithost/gerrit/a/changes/884120

Answer 3

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.

Answer 4

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.