Contributing to Mercurial through Heptapod

This document summarizes the contribution and review process for contributing to Mercurial using Heptapod.

Heptapod is a friendly fork of GitLab Community Edition that also supports Mercurial. https://foss.heptapod.net is a public instance for Free and Open-Source Software (more information here).

1. For contributors

1.1. Building Your Changes

Each contribution should be made in a series of small and independent patches, see ContributingChanges.

This series should be part of a topic, a form of lightweight branching provided by the topic extension. We strongly recommend you enable the evolve extension too from the same Python package. We recommend the Quickstart Guide from Heptapod itself

1.2. Sharing and testing your changes

You need to create an account on foss.heptapod.net and request Developer access to the project by clicking the link just under the logo, it should be granted to you very quickly. We have plans to improve the drive-by contribution experience to remove this step, but the development effort required is non-trivial.

While developing your changes, you can push them to Heptapod to test a full CI run or get early feedback from specific people pre-review. Please note that we may change this automatic-CI-on-push policy in the future if the stress on the CI is too large, restricting it to Merge Requests only.

When you push to Heptapod, you will be offered a link to create a Merge Request (MR) in the CLI. Follow that link to create a MR. Don't worry, you can also create the MR later through the web UI.

You can create a MR early in the development process to make it easier to follow (for example, to have a unique URL to check the results of CI runs), however please mark your MR as "Draft" until it is ready for review. This is done using the prebuilt button in Gitlab.

1.3. Submitting your change for review

When your changes are ready for review, simply take the following actions:

• Mark it as "Ready" (there is a button for that at the top of the MR)

• Assign the reviewer field to the "Mercurial Review" user

The change will then be picked up by reviewers who will provide feedback and eventually accept it.

1.4. Discussing and applying feedback

If some aspect of your patches needs to be clarified or changed, reviewers will:

• Put the MR back into "Draft" status
• Ask questions and request changes to your patches through comments.

When this happens you should apply the feedback and answer the questions using the comment system (make sure you use the threading system for clarity).

Do not mark the thread as resolved, that's the reviewer's responsibility.

Once all feedback and questions have been answered, you should put your series back in the review queue by marking it as "Ready" again.

1.5. When your series is accepted

In the general case, your series will eventually be accepted and become part of the main history.

You don't need to do anything, the changesets will get published (in the Mercurial sense), the topic will fade away and the MR will be automatically detected as merged. If the changesets needed a rebase or some small adjustment, changeset evolution will keep track of that for you and a simple hg evolve after pulling should be enough.

1.6. Getting a series out of the review queue

If a series needs to be stashed away or if lengthy rework is expected, it is useful to get it out of the review queue. To do so:

- mark it as "Draft" again - remove the "Mercurial Review" from the reviewer field.

1.7. Fully abandoning a series

If you want to fully abandon a series, keep track of your topic parent (usually s0 in hg stack), then simply use hg prune -r topic(mytopic) and push the (former) parent of that topic hg push --rev TOPIC_PARENT to remove them from the server. (Pro-tip: any descendant of the topic parent will work)

2. For reviewers

2.1. Checking for series that need review

These are all non-"Draft" series with "Mercurial Review" as a reviewer.

Here's a bookmark: https://foss.heptapod.net/mercurial/mercurial-devel/-/merge_requests?scope=all&state=opened&reviewer_username=project_22_bot2&draft=no

2.2. Providing feedback on a review

If a series needs changes or clarification: - Comment to provide feedback and use threads as much as possible, - Mark the MR as "Draft"

As a general rule, comments about a specific changeset should go on its diff, and comments about the whole series should go to the general discussion page.

The reviewer (you), is responsible for marking thread as resolved. This will be made easy to remember because merging is disallowed through the Web UI when conversations are not resolved.

2.3. Approving a Series

There is an Approve button on MR, click it and your approval will be visible in the UI. This is useful for users that don't have merge rights or simply to signify "I want someone else to also look at this".

2.4. "Merging" the change

Note: this is the GitLab notion of merge which does not necessarily mean a merge changeset. In our case, we will forbid merge changesets and only allow fast-forward merging.

If a series is ready to be merged, click the merge button.

Merging a series is only possible if the CI passed and the changes are rebased on the current branch head.

If you want to partially merge a series, create a new topic with a new MR to do so. This validates that the CI is happy on the change you are about to merge.

3. Current issues

3.1. Per-commit thread

We cannot currently easily comment on the commit message. Gitlab is actively working on it. The effort can be tracked here: https://gitlab.com/gitlab-org/gitlab/-/issues/19691.

In the meantime, people can still quote commit messages in regular comments and use the first line of the commit for example.

3.2. Stacked topics

• Merging a stacked topic currently also merges the underlying topics
• All changesets (and changes in the full diff) from the underlying topics are visible in the stacked MR when reviewing
• There is no obvious way of telling apart changes from the current topic and from the ones below

Work on improving these issues is underway, but it takes time, so please bear with us. Help is always appreciated.

4. External tooling

It is fairly easy to connect automation to Gitlab, currently nothing of the sort (that could work well with Mercurial) has been written, but if someone wants to enforce some of our convention with a bot, please go ahead.