#pragma section-numbers 2

= Contributing to Mercurial through Heptapod =

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

[[https://heptapod.net/|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 [[https://foss.heptapod.net/heptapod/foss.heptapod.net|here]]).

⚠ We recommend you start with the [[https://heptapod.net/pages/quick-start-guide.html|Quickstart Guide from Heptapod itself]] ⚠

<<TableOfContents()>>

----

== For Contributors ==

This section will present the workflow from a contributor's perspective.


=== Building Your Changes ===

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

That series of changesets '''must''' 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. This is covered by [[https://heptapod.net/pages/quick-start-guide.html|Heptapod's Quickstart Guide]]

=== Joining the Project on Heptapod ===

You need to create an account on foss.heptapod.net and request `Developer` access to [[https://foss.heptapod.net/mercurial/mercurial-devel|the project]] by clicking the link just under the logo, it should be granted to you very quickly.

People from Octobus have plans to improve the drive-by contribution experience to remove this step, but the development effort required is non-trivial.

=== Sharing and testing your changes ===


While developing your changes, you can push them to Heptapod to test a full CI run<<FootNote(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.)>> or get early feedback from specific people pre-review.


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.

''Note: you can skip the CI if you don't need it yet and want to be a nice neighbor with `hg push -r REV --pushvars ci.skip=`''

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 pre-built button in Gitlab.

=== 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). This is the default when opening an MR, but may be necessary after reviewer feedback
 * Assign the `reviewer` field to the "Mercurial Review" user if not already the case

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

''(There is currently [[https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81472|a bug]] in upstream GitLab that sometimes shows bot users (such as "Mercurial Review") as "****", don't worry if that happens and look for @mercurial.review)''

=== 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. Please 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.

=== 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.

=== 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.

=== 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)

----

== For reviewers ==

This section will present the workflow from a reviewer's perspective.

'''Note that for email patches, you will need to send a merge request with the emailed patch series to wait for the CI to complete and merge the change. You do not need to add "Mercurial Review" to reviewers, this is only a special case to ensure that pre-landing CI is done for email patches.'''

=== Setup ===

First setup yourself to [[https://heptapod.net/pages/quick-start-guide.html|contribute through Heptapod]].

Second, add this to your configuration. '''This is very important to prevent you to publish content by mistake.'''. People from Octobus are working on making this a server-side check soon, for now this is the best we've got.

{{{
[experimental]
auto-publish=abort
}}}

=== 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=mercurial.review&draft=no

=== 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.

=== 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 "Looks good, but I want someone else to also look at this".

=== "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, discussion are resolved 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 about the change you are about to merge.

----

== References ==

=== Series States ===

Here is a summary of the states a series can be in.

|| Reviewer is "Mercurial Review" || Marked "Draft" || Has approvals || Status ||
|| {X}   ||''Any''  || ''Any'' || Series is not part of the review queue and will not be considered ||
||  (./) || (./) || {X} ||  Series needs answers or rework from the author ||
||  (./) || {X} || {X} ||  Series is waiting for review ||
||  (./) || {X} || (./) ||  Series has been pre-reviewed and needs a second review ||

----

== Current issues ==

=== 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.

=== 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 from Octobus, but it takes time, so please bear with us. Help is always appreciated.

== 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.

Example actions that could be useful to script:
 * automatically put series that fail CI back to `Draft`,
 * automatically rebase and "merge" series with enough `Approvals`.

----