A change set in Gerrit refers to a collection of commits that are logically grouped together for review and submission as a unit. In Gerrit, each change represents a single commit, and multiple related changes can form a change set when they are dependent on one another or part of the same feature or task.
Here's how change sets work in Gerrit:
1. Understanding Gerrit's change workflow
- A change is created in Gerrit when a commit is pushed to a branch that is under review.
- Each change is associated with a unique Change-ID, which Gerrit uses to track the lifecycle of the commit through reviews, revisions, and approvals.
- Changes can depend on other changes. These dependencies are often represented as a stack of commits, where the parent change must be merged before the dependent ones.
2. Creating a change set
- To create a change set, you typically create a sequence of dependent commits locally in Git.
- Each commit must include a unique Change-ID in its message. This can be done using Gerrit's
commit-msg
hook, which automatically adds a Change-ID when committing. - When you push these commits to Gerrit for review (e.g., using
git push origin HEAD:refs/for/<branch>
), they are treated as a change set, with Gerrit showing their dependency chain.
3. Managing and reviewing change sets
- Dependency view: Gerrit visually represents dependent changes in a graph or tree structure. Reviewers can see how changes relate to each other and focus on individual changes or the entire set.
- Independent reviews: Each change in a change set is reviewed separately, but the dependent changes cannot be merged until their parent changes are approved and merged.
- Revisions and rebasing: If a parent change is updated, dependent changes may need to be rebased to stay aligned. Gerrit helps manage this by allowing you to rebase changes directly in the UI or through Git commands.
4. Example workflow
Let's assume you are working on a feature that involves three changes:
- Update a library version.
- Add a new API endpoint.
- Write unit tests for the API.
Step-by-step:
Create and commit each change locally in your Git repository:
Terminalgit commit -m "Update library version" # Generates Change-ID: Iabc123git commit -m "Add API endpoint" # Generates Change-ID: Idef456git commit -m "Write API tests" # Generates Change-ID: Ighi789Push the changes as a stack to Gerrit:
Terminalgit push origin HEAD:refs/for/feature-branchIn Gerrit, the changes will appear with their dependencies. For example:
TerminalChange 1 -> Change 2 -> Change 3Reviewers can provide feedback on each change, starting with Change 1. Once Change 1 is merged, Change 2 and Change 3 can be reviewed and merged sequentially.
5. Key benefits of change sets in Gerrit
- Logical grouping: Makes it easier to review related changes.
- Dependency management: Gerrit enforces the correct order of merges, ensuring dependent changes are not integrated prematurely.
- Collaboration: Reviewers and contributors can discuss and revise changes incrementally.
By managing changes as change sets, Gerrit facilitates better review workflows and prevents incomplete or inconsistent code from being merged into the main branch.