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.

The software forges 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 that modern Mercurial with Heptapod can be a good technical choice for this project; in addition, 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, GitLab and GitHub

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 hosted 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

Unless you really know what you’re doing, read at least the first sections of this page before contributing.

Unless you really know what you’re doing, install and setup Mercurial as described below!

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!

• Unlike Git, there is no notion of index in Mercurial. Unless you want to track a new file, there is no need to use hg add. If you want to commit only some of the current 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 usual with GitHub and GitLab, this is not mandatory but (i) not difficult and (ii) much more convenient than using 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, unless you really know what you’re doing, I strongly suggest that you just follow these instructions.

Important

It is really easy with other installation methods to get a broken installation without the topic and evolve extensions and you need them to contribute to this project.

Important

If you have any issue with this step, do not struggle alone more than 2 minutes!!! Explain your problem in our issue tracker or let’s discuss on https://matrix.to/#/#py-edu-fr:matrix.org.

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

initiation, science and JupyterLite

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

gallery

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

Note

No need to fork! No kidding, you just 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