[COMING SOON] Mercurial

• Mercurial access
• Repositories
• Developer workflow
• Draft topics for work in progress and pullups
• Complicated pullup: firefox update

---

Mercurial access

Developers MUST clone from hg.test.NetBSD.org in order to push to it. Developers MUST NOT push anything to hg.test.NetBSD.org based on cloning or pulling from anonhg.test.NetBSD.org.

Repositories

Main repositories.  The main repositories such as src and pkgsrc, without the “@draft” suffix, have the main history of the project.

Changesets in the main repositories cannot be amended or reordered, and—outside the vendor/* namespace—new branches may only be created by releng and admins.

Draft repositories.  The “@draft” repositories are for work in progress changsets still in the draft phase on a topic, which may be created, amended, reordered, or pruned by any developer at any time, using the Mercurial “evolve” and “topic” extensions (devel/py-hg-evolve in pkgsrc). Once a changeset is pushed to the main repository, it transitions from draft phase to public phase and can no longer be changed.

A changeset by developer jrandomdev@NetBSD.org meant for the next NetBSD 11.x release to fix the veeblefitzer for PR 12345, for example, should be committed on the topic “jrandomdev-pr12345-fixveeblefitzer” for branch “netbsd-11”, and can be pushed to src@draft to share it. The changeset can be amended and pushed again during review. Releng can then merge it into the “netbsd-11” branch and push it to src, at which point it can no longer be amended. Old revisions of drafts are not deleted—they can be browsed with “hg obslog”, but are otherwise hidden from view.

Mercurial draft topics correspond to Git branches in the “@draft” repositories, but provide a smoother experience than Git is capable of, for amending and maintaining changes on top of drafts with Mercurial changeset evolution.

Developer workflow

Software prerequisites.  Install devel/mercurial and devel/py-hg-evolve from pkgsrc. Create a file ~/.hgrc with the following contents to configure what name Mercurial will put on changesets you make, and to enable relevant extensions:

[ui]
username = J. Random Developer <jrandomdev@NetBSD.org>

[extensions]
evolve =
histedit =
rebase =
share =
topic =

We also recommend the following cosmetic options to make draft changesets you haven't pushed yet (and secret changesets Mercurial will refuse to push) stand out more:

[color]
changeset.draft = red bold
changeset.secret = red bold inverse

You can alternatively configure Mercurial on a per-repository basis instead by editing $REPO/.hg/hgrc instead; see hg help on configuration for more details.

To start.  Clone the Mercurial repository:

$ hg clone ssh://jrandomdev@hg.test.NetBSD.org/src

The initial clone may take a long time, and if interrupted, Mercurial is unable to automatically save its progress and pick up where it left off. (XXX Need to describe alternatives: clone/pull --depth, or downloading bundle separately (requires manual verification of hash, though), or remotefilelog with clone --shallow. XXX) You can also have multiple working trees sharing the same repository data, e.g. to work on checkouts of two different topics at the same time, using “hg share src src1” (requires enabling the “share” extension).

To make and publish changes.  Once you have edited some files in the working tree, such as “sys/kern/kern_wotsit.c”:

If someone else has already pushed changes since you last updated, you will see a message like this:

$ hg push
abort: push creates new remote head f4773da82bc0
(pull and merge or see 'hg help push' for details about pushing new heads)

Do not merge; instead, rebase. We require a linear history, but Mercurial currently has no way to configure this message. So you should pull, rebase, and retry:

$ hg pull
$ hg rebase
$ hg push

You can also use “hg pull --rebase” as a shorter equivalent of “hg pull && hg rebase”.

Note: Developers must set $USER@NetBSD.org or $USER@pkgsrc.org as the email address for changesets by setting “ui.username” in the per-user ~/.hgrc or the per-repository $REPO/.hg/hgrc file.

If you already made a changeset but can't push it because it has the wrong email address, you can fix it with “hg commit --amend --current-user”. If you made multiple changesets, you can edit them with “hg histedit”; see “hg help -e histedit” for details.

Note that the equivalent of “cvs commit” is two steps in hg: 1. “hg commit” to locally create a changeset, and then 2. “hg push” to publish it to the central repository.

To track development.  From the src directory, pull new changes from the central repository:

$ hg pull

Update your working tree to the latest upstream change on the current branch:

$ hg update

This won't discard any local changesets, but if you want to push them later, you will need to rebase them first—the history is required to be linear:

$ hg rebase

If “hg rebase” fails with merge conflicts, you must resolve them and record the resolution with “hg resolve” and “hg rebase --continue” before proceeding. You can also “hg rebase --abort” to go back to the way things were before you started rebase in case you want to start over. And if your working tree is clean, you can always use “hg update $REV” to switch it to a particular revision without losing anything.

If you get lost.  Before you adapt the xkcd git procedure to Mercurial, review the output of these commands, and share them with developers or admins you're asking for help, as well as the contents of ~/.hgrc and $REPO/.hg/hgrc, and the output of any command you're having trouble with:

$ hg summary
$ hg status
$ hg log -pvr .
$ hg log -G -T phases

Draft topics for work in progress and pullups

If you are working on a change that is not “ready for commit”, you can put it on a topic and push it to the “@draft” repository where you are free to edit and amend it before it is applied to the main branch.

To create a topic.  To start work on a topic, say to fix PR pkg/12345 in pkgsrc, make sure you're on the branch the change is meant for, and set the topic:

$ hg update default
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg topic riastradh-pr12345-fixlddrequiresprovides
marked working directory as topic: riastradh-pr12345-fixlddrequiresprovides

Any changesets you commit after this will be labelled with the topic “riastradh-pr12345-fixlddrequiresprovides”:

$ edit mk/pkgformat/pkg/metadata.mk
$ hg commit -m 'WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd.'
active topic 'riastradh-pr12345-fixlddrequiresprovides' grew its first changeset
(see 'hg help topics' for more information)
$ hg parent
changeset:   456212:b19048b50903
tag:         tip
topic:       riastradh-pr12345-fixlddrequiresprovides
parent:      456183:864be844ceb6
user:        Taylor R Campbell <riastradh@pkgsrc.org>
date:        Sat Nov 01 23:55:19 2025 +0000
summary:     WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd.

The topic is a label to keep such draft changes organized during this time—it's part of the changeset's identity, but it will be hidden when the changeset is pushed to pkgsrc proper, so it doesn't matter too much.

To keep topics organized, you should name them with your user name, a PR number if applicable or a date if not, and a short descriptor for what it's about. Each branch has its own namespace of topics, so you can, say, use the same topic name on the main branch, “default”, and on the “pkgsrc-2025Q3” branch to prepare a pullup by “hg graft” of the main branch changeset.

If you accidentally created a draft changeset on the wrong topic or no topic, you can amend it with, e.g.: “hg topic -r . riastradh-pr12345-fixlddrequiresprovides”.

You can share this draft with others by pushing it to the “@draft” repository:

$ hg push -t riastradh-pr12345-fixlddrequiresprovides ssh://hg.test.NetBSD.org/pkgsrc@draft

(If you want to check first what hg would push without actually pushing, you can use “hg outgoing” instead of “hg push”.)

If you start the commit message with “WIP:”, the main repository will refuse to let you push it; this way you can avoid accidentally publishing a draft before it's ready, if you run plain “hg push” out of habit. You can also configure how plain “hg push” behaves by setting the “paths.default”, “paths.default:pushurl”, and “paths.default:pushrev” options; see hg help on paths config for details. You can also make an abbreviation “hg push draft” push to the full URL by adding

[paths]
draft = ssh://jrandomdev@hg.test.NetBSD.org/pkgsrc@draft

to $REPO/.hg/hgrc.

To make changes to a topic.  As others review the draft and request changes, you can amend it and push your updates like you pushed the original:

$ hg parent
changeset:   456212:b19048b50903
tag:         tip
topic:       riastradh-pr12345-fixlddrequiresprovides
parent:      456183:864be844ceb6
user:        Taylor R Campbell <riastradh@pkgsrc.org>
date:        Sat Nov 01 23:55:19 2025 +0000
summary:     WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd.

$ hg pull --rebase
...
$ edit mk/pkgformat/pkg/metadata.mk
$ hg amend -m 'WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd, v2.'
$ hg parent
changeset:   456213:fa522c253346
branch:      trunk
tag:         tip
topic:       riastradh-pr12345-fixlddrequiresprovides
parent:      456183:864be844ceb6
user:        Taylor R Campbell <riastradh@pkgsrc.org>
date:        Sat Nov 01 23:55:19 2025 +0000
summary:     WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd, v2.

$ hg push -t riastradh-pr12345-fixlddrequiresprovides ssh://hg.test.NetBSD.org/pkgsrc@draft
pushing to ssh://hg.test.NetBSD.org/pkgsrc@draft
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
1 new obsolescence markers

Now when other users pull the topic, they'll get the new revision of the changeset. And anyone who has made changes on top of the original revision of your changeset need only run “hg evolve” to reapply their changes on top of your updated revision. You can review the history of revisions to this changeset using “hg obslog”:

$ hg obslog
@  fa522c253346 (456213) WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd, v2.
|    amended(content) from b19048b50903 using amend by Taylor R Campbell <riastradh@pkgsrc.org> (Sun Nov 02 00:10:31 2025 +0000)
|
x  b19048b50903 (456212) WIP: mk: Fix REQUIRES/PROVIDES with readelf instead of ldd.

The older revisions of the changeset aren't normally shown in “hg log” or accepted by “hg diff”, but they are available if you pass “--hidden”.

To pull a draft topic for review and testing.  When someone has published a draft a topic “riastradh-pr12345-fixlddrequiresprovides”, you can pull it from the “@draft” repository:

$ hg pull -r riastradh-pr12345-fixlddrequiresprovides ssh://hg.test.NetBSD.org/pkgsrc@draft

If it's a draft topic for a branch other than the default branch, such as a pullup to a stable branch, use the “fully-qualified branch name” adjoining the branch name and the topic name with “//”:

$ hg pull -r netbsd-11//jrandomdev-pr31415-typofixes ssh://hg.test.NetBSD.org/src@draft

When a draft topic is done.  We require the history to be linear, so first rebase the changes onto the main branch:

$ hg pull
$ hg update riastradh-pr12345-fixlddrequiresprovides
$ hg rebase

If that succeeded with no merge conflicts (and if any applicable tests still pass), then you can publish it by pushing it to the main repository:

$ hg push -r .

If you had commit messages starting with “WIP:”, you'll need to edit them with “hg commit --amend” or “hg histedit” before you can push to the main repository.

In the future, we may make it mandatory for all changes to start as draft topics for automatic verification and testing before being merged to the main branch.

To draft a pullup.  If you have a change you want to pull up so that appears in the next NetBSD 11.x release, switch to the “netbsd-11” branch, create a topic on it for the pullup, and use “hg graft” to reapply the change on the branch:

$ hg update netbsd-11
$ hg topic jrandomdev-pr31415-typofixes
$ hg graft 01234abcd
$ hg push -r . ssh://jrandomdev@hg.test.NetBSD.org/src@draft

Then you can ask releng to pull up the topic “jrandomdev-pr31415-typofixes” on the “netbsd-11” branch.

Complicated pullup: firefox update

We want to backport an update to firefox to pkgsrc-2018Q4, which has firefox 64.0. First, locate the commits we want to backport:

$ hg update pkgsrc-2018Q4
$ hg topic maya-20190101-firefox65
$ cd www/firefox
$ hg log .
changeset:   318928:08850549da8a
branch:      trunk
user:        ryoon <ryoon@pkgsrc.org>
date:        Fri Feb 01 16:47:59 2019 +0000
summary:     Bump PKGREVISION

changeset:   318799:ae2a80757ebc
branch:      trunk
user:        tnn <tnn@pkgsrc.org>
date:        Tue Jan 29 22:33:57 2019 +0000
summary:     remove obsolete hacks.mk & reduce diffs between mozilla derivative packages

changeset:   318788:3b3b81d77487
branch:      trunk
user:        ryoon <ryoon@pkgsrc.org>
date:        Tue Jan 29 16:28:22 2019 +0000
summary:     Updatet to 65.0

changeset:   318321:e0a4a2cb523a
branch:      trunk
user:        jperkin <jperkin@pkgsrc.org>
date:        Wed Jan 23 15:45:48 2019 +0000
summary:     firefox: Remove -pie on SunOS.

changeset:   317595:55e70f55a5a6
branch:      trunk
user:        ryoon <ryoon@pkgsrc.org>
date:        Thu Jan 10 13:37:40 2019 +0000
summary:     Update to 64.0.2

changeset:   316976:e0780dfada82
branch:      trunk
user:        gutteridge <gutteridge@pkgsrc.org>
date:        Sun Dec 23 01:11:26 2018 +0000
summary:     firefox: fix .mk file inclusion order issue

changeset:   316509:6024a48bce43
branch:      trunk
user:        prlw1 <prlw1@pkgsrc.org>
date:        Fri Dec 14 10:21:27 2018 +0000
summary:     Fix build with webrtc option.

changeset:   316413:c57c62ca7a2d
branch:      trunk
user:        ryoon <ryoon@pkgsrc.org>
date:        Wed Dec 12 14:08:50 2018 +0000
summary:     Update to 64.0

We need the changes after 316413 (not including) to update 64->65. Let's naively try to combine all of them:

$ hg graft 316509 316976 317595 318321 318788 318799 318928
skipping ancestor revision 316509:6024a48bce43
skipping ancestor revision 316976:e0780dfada82
grafting 317595:55e70f55a5a6 "Update to 64.0.2"
grafting 318321:e0a4a2cb523a "firefox: Remove -pie on SunOS."
grafting 318788:3b3b81d77487 "Updatet to 65.0"
grafting 318799:ae2a80757ebc "remove obsolete hacks.mk & reduce diffs between mozilla derivative packages"
merging mail/thunderbird/Makefile
merge: warning: conflicts during merge
merging mail/thunderbird/Makefile failed!
abort: unresolved conflicts, can't continue
(use 'hg resolve' and 'hg graft --continue')

This doesn't work because the commit:

318799:ae2a80757ebc "remove obsolete hacks.mk & reduce diffs between mozilla derivative packages"

has changes to multiple packages, and we don't want to pullup mail/thunderbird at this time.

Let's use “hg resolve” to tell Mercurial how to resolve the conflicts—by keeping mail/thunderbird as it was locally and discarding the changes:

$ hg resolve -t internal:local ../../mail/thunderbird
continue: hg graft --continue
$ hg graft --continue
grafting 318928:08850549da8a "Bump PKGREVISION"

Test to make sure the package still works, and then you can push it and ask releng to pull up topic “maya-20190101-firefox65” to the “pkgsrc-2018Q4” stable branch.