Mergebot

• Mergebot Workflow
  • For developers
  • For reviewers
  • Commands
    • Merge mode configuration
• Forward Port Workflow
  • Commands
  • Conflict
  • Edition of a forward-port PR

Introduction

The merge bot is a tool to orchestrate pull requests merging into the stable branches of Odoo.

Odoo workflow

For a developer

1. Create your PR
2. Squash appropriate commits to keep only meaningful ones
3. Write commit messages respecting the commit guidelines
4. If your PR contains more than one commit, clean the pull request description to match the commit guidelines too (it will be used as the merge commit message)
5. Ask a review to one of the authorized reviewers

For a reviewer

1. Review the pull request (actually a mandatory step).
2. If there are multiple reviews requested, you can use Github's "Approve", otherwise skip to next step.
3. If all reviewers have approved, either use review+ or delegate, to start the merging process.
4. If the PR contains multiple commits, configure its integration mode

Available Commands

A command string is a line starting with the mergebot's name (robodoo, @ prefix optional) and followed by various commands.

• retry

  resets a PR in error mode to ready for staging

  can be used by a reviewer or the PR author to re-stage the PR after it's been updated or the target has been updated & fixed.

• r(eview)+

  approves a PR, can be used by a reviewer or delegate reviewer

  submitting an "approve" review implicitly r+'s the PR

• r(eview)-

  removes approval from a PR, allows un-reviewing a PR in error (staging failed) so it can be updated and re-submitted

  if a PR is staged and unreviewed, the staging is cancelled

• delegate=<users>

  adds the specified users as reviewers for this pull request. Can be used by reviewers

  <users> is a comma-separated list of github usernames (no @ prefix)

• delegate+

  shortcut for delegate=<pr-author>

• p(riority)=2|1|0

  sets the priority to normal (2), pressing (1) or urgent (0), lower-priority PRs are selected first and batched together, can be used by reviewers

  • priority 2 (the default) means the PR will be staged after other priorities and splits
  • priority 1 means the PR will be staged before splits
  • priority 0 is similar to priority 1 but stages without needing approval (review) or runbot to pass on the PR, "unreviewing" (r-) such a PR automatically re-sets it to p=1

• override=<status>

  Allows overriding whatever status was automatically generated for a branch. The override is persistently linked to the pull request, status updates on the PR will be ignored. Example: override=ci/security

  Override rights must be configured individually on users, for each status to be overridden ; they are purposely independent from general review rights.

merge modes

When a PR contains more than one commit, a merge method has to be selected:

• merge

  integrates the PR via a regular merge commit, without rebasing, the PR title and body are used to create the message of the merge commit

• rebase-merge

  rebases the PR then integrates it via a regular merge commit, the PR title and body are used to create the message of the merge commit

• rebase-ff

  rebases the PR then integrates it via a fast-forward (all the commits of the PR are copied to the target), this is the behaviour when the PR has a single commit as well

Examples

Simple

1. @alice creates a PR, write a good commit message and asks a review to @bob

2. @bob writes a message to approve the PR

   robodoo review+

3. @robodoo rebases and merges the PR

Delegation

1. @alice creates a PR, write a good commit message and asks a review to @bob

2. @bob is not certain of the content and would like a second opinion from @carol (who is not an authorized reviewer)

   robodoo delegate=carol

3. @carol agrees with the PR and approves

   robodoo r+ 👍

4. @robodoo rebases and merges the PR

Error

1. @alice creates a PR, writes a good commit message and asks a review to @bob

2. @bob approves the PR with r+

3. @robodoo tries to merge it but it fails (e.g. test fail or conflict after rebase); it posts a message on PR

   Staging failed: ci/runbot failed on 4a0b13ed923

4. @alice corrects the PR

5. As the content has changed, @bob validates again the PR

   robodoo r+ please

6. @robodoo rebases and merges the PR

Merge a community's contribution

1. @alice (community member) creates a PR and asks a review to @bob

2. @bob (reviewer) wants to slightly clean up the PR to apply code/commit guidelines

3. As @alice, by default, allows commits in her branch when creating a PR, @bob can add the remote, fetch and checkout the branch (or, if he is lazy, use an alias to set in his ~/.gitconfig to do the same)

   $ git get-br alice:11.0-awesome-fix
   $ git commit --amend
   $ git push --force-with-lease alice 11.0-awesome-fix
   

4. Once the PR is ready, @bob approves the amended version

   robodoo review+

5. @robodoo rebases and merges the PR

Multiple commits with a regular merge

1. @alice creates a PR containing multiple commits, writes a good PR title and body and asks a review to @bob

2. @bob writes the following message to approve the PR

   robodoo r+

3. @robodoo sends a feedback message on the github PR like this one:

   Because this PR has multiple commits, I need to know how to merge it:

   merge to merge directly, using the PR as merge commit message rebase-merge to rebase and merge, using the PR as merge commit message rebase-ff to rebase and fast-forward

4. @alice sets the merge method to merge

   robodoo merge

5. @robodoo creates a merge commit with the PR title and body as commit message

Multiple commits with a rebase and a merge commit

1. @alice creates a PR containing multiple commits, writes a good PR title and body and asks a review to @bob

2. @bob writes the following message to set the merge method and approves the PR

   robodoo rebase-merge r+

3. @robodoo rebases and creates a merge commit with the PR title and body as commit message

Multiple commits with a rebase and fast-forward

1. @alice creates a PR with multiple commits and good commit messages. She asks a review to @bob

2. @alice wants the commits to be fast-forwarded, she sets the merge method

   robodoo rebase-ff

3. @bob writes a message to set the merge method and approves the PR

   robodoo review+

4. @robodoo rebases and fast-forwards the PR commits

Forward-port

A branch should target the lowest version where the bug is reproducible and then be forward ported to upper versions.

The forward ports are automatically created by @fw-bot once your PR is merged. The following commands need to be specified before the merge, otherwise the bot can not take them into account.

Forward-ported pull-requests automatically get the same merge mode as their original.

Commands

• up to <version>

  To use on the original PR before it is merged.

  Allows setting a forward port limit (e.g. up to 12.0), by default a pull request is forward-ported to all still-supported later versions. The limit is inclusive.

  Forward-port can be disabled by providing the original PR's target as limit e.g. if the PR was created targeting 10.0, specifying up to 10.0 will not do any forward-porting.

• ignore

  To use on the original PR before it is merged. Disables the forward-port of this PR (similar to specifying up to <pr target>)

• close

  Allows closing forward-port pull requests if you're the author of the original, even if you can't normally close PRs (no write access to the repository).

• r+

  To be done on the last PR that has to be merged. All the PR targeting the previous versions will be merged. Can be done by anyone having robodoo r+ rights and the author of the source PR.

Example:

1. Create a branch in v11, create a PR.

2. Follow the usual review process with @robodoo and with an optional fw-odoo command

   @robodoo r+

   @fw-bot up to saas-12.3

3. As soon as the PR is merged, the @fw-bot will create a PR in version N + 1, in this case v11.3

4. If the v11.3 runbot is green, a PR is created in v12.0.

5. If the v12 runbot is green, a PR is created in v12.3 (the specified limit).

6. When the v12.3 runbot is green, you can proceed on the PR for v12.3: "@fw-bot r+"

7. Every forward port PR, from v11.3 to v12.3 will be merged

Interrupted chain

If runbot fails on a forward-port PR, the chain will get interrupted as the bot awaits further action.

If this is a false-positive runbot failure, you can just rebuild, as soon as runbot succeeds the forward-port will continue as if nothing had happened.

If this is a real failure, you will need to edit the pull-request.

Conflict

If a conflict occurs while creating a forward-port PR, the chain will get broken, you will have to edit it to resolve the conflict, either in-place if there is a single commit or doing your own cherry-pick to re-do the forward-port resolving the conflicts.

Alternatively, the pull request can be closed (and ignored) if it turns out redundant or unnecessary from this point onwards.

Edition

A forward-port pull-request can be edited by pushing commits to it (either pushing new commits or editing and force-pushing commits). This puts the pull-request into a semi-manual mode:

• the pull-request will have to be approved via the merge bot
• the forward-port process will then resume up to the limit originally configured (if any)
• if the edited pull-request already has forward-port descendants, those descendants will automatically get updated to match

Example:

1. Create a branch in v11, create a PR and r+ it
2. As soon as the PR is merged, the @fw-bot will create a PR in version N + 1, in this case v11.3
3. If the v11.3 runbot is green, a PR is created in v12.0.
4. If the v12.0 PR fails because of a merge conflict, solve the conflict manually and ask @robodoo to merge it when ready. You will also need to @fw-bot r+ the 11.3 PR (so all PRs of the chain up to 11.3 are merged)
5. The @fw-bot will create a PR in version 12.3 based on the 12.0 port (in essence, it's the 12.0 PR that is now being forward-ported, the 11.0 PR is closed).