Heptapod and Mercurial

Modern Mercurial

Mercurial is a versioning tool like Git (same generation and similar theoretical bases). For very simple things, it is quite similar to Git. However, there are also important differences.

Github and Gitlab do not support Mercurial. Git became for open-source THE tool used for versioning all kinds of projects.

However, Mercurial has been used in companies of all sizes for years and grew up as a great tool, with advantages compared to Git, in particular in terms of simple user interface, safety (no force push needed, no destructive history edition), performance for big repositories (with a growing part written in Rust) and collaborative history edition (with this Mercurial extensions evolve and topic).

Currently, we are experimenting with using Mercurial instead of Git. I (Pierre Augier) think than modern Mercurial with Heptapod can be a good technical choice for this project. Using Mercurial for this project would tend to increase the diversity in terms of versioning tools which is a good thing considering the current situation of Git monopoly.

Heptapod and GitLab

Heptapod is a GitLab fork supporting Git and Mercurial. GitLab is an open-source development platform. In contrast to Github, which is a proprietary platform (owned by Microsoft), instances of GitLab or Heptapod can be run by anyone (for example universities or public institutions).

However, since most potential developers are used to Git, it represents a technical barrier for contribution. We try to make this barrier as small as possible by providing good documentation on contributing with Heptapod and Mercurial.

Important

Except if you really know what you do, read at least the first sections of this page before contributing.

Get the developer or maintainer role

No need to fork the repositories to contribute! The first step instead is to log in on https://foss.heptapod.net (one can use a Github or Gitlab account) and send a message in this issue to get the “developer” or “maintainer” role for https://foss.heptapod.net/py-edu-fr.

Contribute via the web interface

Once you became “developer” or “maintainer” of the project, you can modify a file via the web interface. Click on edit in the Heptapod interface showing a file, edit the file and commit the changes in a new Gitlab branch.

Important

Since the GitLab branch HAS to corresponds to a Mercurial topic, you HAVE to choose a name in the form topic/default/my-nice-topic-name (replace my-nice-topic-name with something appropriate).

Contribute with local development using Mercurial

Differences compared to the common Github workflow

• No need to fork the repo to contribute!

• hg pull just gets the commits and does not update to the tip of the current branch.

• For feature branches, we use Mercurial topics. To create a new feature branch use

  hg pull
  hg up default
  hg topic my-topic-name
  

  and not hg branch my-name-name, which corresponds to something else in Mercurial!

• No Git index in Mercurial. Most of the time (no new/removed files) no need to use hg add. If you want to commit only few changes, you can use hg commit my_file or hg commit -i (interactive).

Add a ssh key to foss.heptapod.net

Add a ssh key here https://foss.heptapod.net/-/user_settings/ssh_keys. As usually with Github and Gitlab, this is not mandatory but (i) not difficult and (ii) much more convenient than with https in the long term.

Install and setup modern Mercurial

For this project, we use modern Mercurial using the topic and evolve extensions. General Mercurial installation instructions are given here https://www.mercurial-scm.org/install, however, except if you really know what you do, I suggest that you just follow the following instructions. Since Mercurial is a Python application, recent versions can be installed with UV or Pipx. However, for Windows it is still better to just download and install TortoiseHG, so for Windows skip the first step.

• Install Mercurial and its extensions (Unix)

  UV

  uv tool install mercurial --with hg-git --with hg-evolve
  

  pipx

  pipx install mercurial
  pipx inject mercurial hg-git hg-evolve
  

• Check that hg corresponds to the Mercurial installed with UV or Pipx

  hg debuginstall
  

  Not using the right hg?

  Importantly, the directory where UV/Pipx puts the executables has to be before other directories where older Mercurial can be present so that hg really corresponds to the Mercurial install with UV/Pipx. You can check the environment variable $PATH.

• Setup Mercurial (config file ~/.hgrc and completion) (Unix and Windows)

  UV

  uvx hg-setup init
  # complete information, save the config file and quit hg-setup
  

  pipx

  pipx run hg-setup init
  # complete information, save the config file and quit hg-setup
  

• Check that everything is fine. Are evolve and topic indeed enabled?

  hg version -v
  

Clone the repository

Finally, you should be able to clone a repo with

main website

hg clone ssh://hg@foss.heptapod.net/py-edu-fr/py-edu-fr.pages.heptapod.net py-edu-fr-website

science

hg clone ssh://hg@foss.heptapod.net/py-edu-fr/py-edu-fr-science

jupyterlite

hg clone ssh://hg@foss.heptapod.net/py-edu-fr/py-edu-fr-jupyterlite

initiation

hg clone ssh://hg@foss.heptapod.net/py-edu-fr/py-edu-fr-initiation

gallery

hg clone ssh://hg@foss.heptapod.net/py-edu-fr/py-edu-fr-gallery

Note

No need to fork! No kidding, you have to copy/paste exactly this line.

Commit and send changes

This project uses basically the same workflow as Mercurial itself: see https://wiki.mercurial-scm.org/Heptapod for a more thorough overview.

To submit a topic-based merge request, use things like:

• Example short version:

hg pull
# up or update
hg up default
hg topic improve-something
#
# file edition ...
#
make format
make
hg commit -m "setup: fix ..."
hg push

• Example longer version:

hg pull
# lg is an alias for log --graph (check the `@` to see where you are)
hg lg
# up or update
hg up default
hg topic improve-something
hg sum
#
# edit/add/remove files...
#
# format the code
make format
# check that it builds
make
# st or status: list files status
hg st
# if there are new or deleted files, one can use hg add, hg addre or hg remove
# list the commits in the topic
hg stack
hg diff
hg meld
hg commit -m "setup: fix ..."
hg push

Get some help

hg help and hg help a-command are your friends. You can read the help for commands and other subjects in https://www.mercurial-scm.org/.

If you encounter issues with Mercurial while working on py-edu-fr, do not hesitate to open an issue in our issue tracker and/or ask questions/explain problems in our dedicated chat.

Introduction to history edition with Mercurial

With the topic and evolve extensions, Mercurial is strong for collaborative and safe history edition. One can watch this short video to discover what it means.

When you work on a topic, the following commands can be useful for you.

hg stack
# list all changesets in a topic and other information

hg evolve
# fix common issues related to collaborative history edition
# you will be told when you need to use this command

hg rebase
# most of the time rebase can be used without argument and does the right thing

hg amend
# modify a commit
hg amend --edit
# to edit the commit message

hg absorb
# incorporate corrections into the stack of draft changesets