2

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.

leeyuiwah
  • 6,562
  • 8
  • 41
  • 71
  • You say *This number plays an important role in understand the Gerrit workflow...* but the docs say *Understanding the format of this ref is not required for working with Gerrit.* Why do find it important? In general, if a detail is not necessary to use a thing it's often better not to document it. Documentation is a promise, and making unnecessary promises can box the developers into a corner. – Schwern Mar 13 '18 at 19:34
  • @Schwern -- Our team was migrated from SVN where we used to have a monotonically increasing number (release number) assigned with every change. Now that we are using Git/Gerrit, we were often asked "what is the number that uniquely identifies a change?" And I found that there are three numbers/IDs: Git Hash, Gerrit Change-Id, and (numeric) Gerrit Change Number. It seems to me that the latter two both uniquely identify a "Gerrit Change" (which can have multiple patch sets) but the Id is hard to use (long hash string) and the numeric number is easy to use yet often not mentioned in doc .... – leeyuiwah Mar 13 '18 at 19:45
  • (cont'd) Perhaps it was because of that I often think maybe Gerrit plans to use the ID to supercede the numeric number. – leeyuiwah Mar 13 '18 at 19:46
  • 1
    FWIW I'm not a fan of Gerrit for exactly that reason: it preserves much of the linear, monotomic SVN workflow. Git is neither linear nor monotomic. Pretending it is helps SVN users in the short term, but causes confusion in the long term and takes away a lot of the power and flexibility of Git. You are correct that they both uniquely identify the change, but the one you should be referring to is the Change Number. The Change-ID is a bookkeeping thing. As for the ID being long, you can safely refer to just the first 8 characters or so; statistically they will be unique. – Schwern Mar 13 '18 at 19:50
  • Change-ID that starts with I is not unique. Consider a scenario where you have a change A in branch X and a project T. Now you cherry-pick the change into branch Y within the same repo T. In this case, both the change will have the same Change-ID. The only way to distinguish between these two changes is by their URL or say Change Number. In this case, the change number is unique but not change-id. – Swapnil Gangrade May 13 '21 at 05:22

4 Answers4

2

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.

Marcelo Ávila de Oliveira
  • 19,950
  • 3
  • 39
  • 50
1

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.

Community
  • 1
  • 1
Schwern
  • 153,029
  • 25
  • 195
  • 336
  • Thanks! I think I under Change-Id. I just want to know more about the numeric Change Number and its limits and properties. – leeyuiwah Mar 13 '18 at 19:53
  • @leeyuiwah I doubt the Change Number has any properties beyond allowing the user to uniquely identify a change. Internally, it's probably the directory used by Gerrit to store change information in your `.git/` directory. – Schwern Mar 13 '18 at 19:55
  • I add an answer of my own with four observations (see below). Do you agree with them? Thanks! – leeyuiwah Mar 14 '18 at 22:24
1

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
ElpieKay
  • 27,194
  • 6
  • 32
  • 53
0

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.
leeyuiwah
  • 6,562
  • 8
  • 41
  • 71
  • 1
    That's basically all correct. #4 is an implemention detail, there's no guarantee that it will be monotonically increasing, just that it will be unique for your server. It's likely because the change number is an auto incremented primary key from the database. – Schwern Mar 14 '18 at 22:34
  • Thanks! I updated my answer to add the qualifier "typically" to the first sentence of #4 – leeyuiwah Mar 14 '18 at 23:01
  • 1
    Gerrit Change-ID that starts with I is not unique in some cases. Consider a scenario where you have a change A in branch X and a project T. Now you cherry-pick the change into branch Y within the same repo T. In this case, both the change will have the same Change-ID. The only way to distinguish between these two changes is by their URL or say Change Number. In this case, the change number is unique but not change-id. – Swapnil Gangrade May 13 '21 at 05:26