Salsa provides services which partially replace some features of the former ?Alioth service. The following hints may help you to move your packaging collaboration effort from Alioth to Salsa.

Many ?Alioth features are (intentionally) not provided by the Salsa platform. You may want to take a look at the related discussion during a sprint for the detailed reasons for this decision.

There is potential overlap between this section and the ?Alioth#Deprecation_of_Alioth documentation. Be careful to avoid adding documentation here that's already there and vice versa. Add links instead, as is already done. Also consider contributing documentation to the generic Salsa/Doc documentation instead if it can be useful for new Salsa users that don't know or care about Gitlab as well. -- TheAnarcat 2018-03-13 16:09:16

Canonical Repository URLs

See Salsa/Doc#Canonical_URLS for the new URLs.

Custom Hooks

For security reasons it is not allowed to run arbitrary custom hooks on repositories. You may want to write yourself a webhook receiver and put your custom actions into such a one.

Alternatively you may use the common webhook receiver or even enhance it with new features, see https://salsa.debian.org/salsa/webhook for details on it.

Import git repository

There are three ways of importing git repositories:

  1. by hand
  2. using two shell scripts
  3. using one python script

The above process takes care of creating the new repository on Salsa and disabling the other on Alioth. But you may also want to add an HTTP redirect from the old repository on Alioth to the new one on Salsa (git:// and git+ssh:// cannot be redirected, so you should still make sure to add the pre-receive hook below). You can do this by sending a merge request for AliothRewriter.

You will obviously also need to change debian/control in the Debian package once the repository is migrated.

To find repositories to migrate, you might like the following find commandline:

$ find ~/src -ipath '*.git/config' -exec grep -H 'url.*git\.debian' '{}' \;

Replace ~/src by the directory containing your git repositories.

By hand

This involves going through the GitLab web interface and importing the git repo by creating a project and specifying the URL.

Once a repo was migrated please remove it.

Using two shells scripts

This is currently done by hand but Christoph Berg's wrote a handy batch import script that you can use to import your projects semi-automatically. The process is somewhat slow (~40 seconds per repo) because of a bug in GitLab's API.

You can then disable the repository on Alioth with ~anarcat/bin/disable-repository <path-to-git-repo> <salsa-path>. path-to-git-repo is the path to the repo on Alioth's filesystem, for example, /git/collab-maint/magic-wormhole.git while salsa-path is whatever comes after salsa.debian.org in the gitlab URLs, for example /debian/magic-wormhole

A copy of this script is available in the alioth-migration salsa repository.

Using a single Python script

The above was all wrapped up in a neat little bundle where you can just call a single script to do it all for you. It will first import the repository (if you provide an API token, which you can create here), then wait for the import to complete before disabling the repository on Alioth.

By default the script is silent but can be made more verbose with the usual --verbose and --debug flags. Logging can also be sent to syslog or a logfile for large automated migrations.

Use:

~anarcat/bin/migrate-repo

to get started. For example, the Sopel and BE repositories were migrated with:

GITLAB_TOKEN=XXXXXXXXX ~anarcat/bin/migrate-repo --debug /git/collab-maint/sopel.git/ /debian/sopel/
GITLAB_TOKEN=XXXXXXXXX ~anarcat/bin/migrate-repo --debug /git/collab-maint/bugs-everywhere.git/ /debian/bugs-everywhere/

Note that the script is fairly idempotent: it will show warnings if the repository is already imported, but it will keep on going otherwise.

A copy of this script is available in the alioth-migration salsa repository.

Import non-git version control repository

Only git repositories are supported by the Salsa platform.

You may want to take a look at the reasons for not supporting other version control systems within Salsa.

Import mailing list

Salsa does not offer any mailing list features on its own (see discussion). There are three options to replace the mailing list:

  1. migrate to lists.debian.org
  2. stay on lists.alioth.debian.org
  3. migrate to tracker.debian.org
  4. use gitlab notifications

See below for details.

alioth-lists.debian.net

A team will migrate lists previously on alioth to a new service. The new name will be alioth-lists.debian.net. An HTTP redirect will provide URL compatibility, and the new system will accept emails for @lists.alioth.debian.org; see Alioth/MailingListContinuation and the announcement.

lists.debian.org

Some mailing lists that were formerly hosted on Alioth may be eligible for being hosted on lists.debian.org. The lists eligible for migration must follow the requirements outlined on the "How to ask a mailing list" guide. The process is also the same as outlined on the guide.

The following kind of lists are probably acceptable for lists.debian.org:

Short version: file a bug on the pseudo-package lists.debian.org with the severity 'wishlist', with the following information:

Lists migrated from Alioth are expected to be open, that is:

If you do want the archive and/or the subscribers to be imported into your new mailing list, please:

The export only works if the 'Is archive file source for public or private archival?' archive setting is true.

Before any migration ensure that there is consensus about the migration and that you have permission from the subscribers. For privacy reasons we expect that the migration process is done by an admin of the list or the alioth project.

Also, please understand that the requirements and features for lists on lists.debian.org are not the same as for a mailing list on Alioth, and the listmaster might reject your request. Lists.debian.org is not supposed to replace all mailing lists and aliases on Alioth.

tracker.debian.org

The package tracker can offer a convenient way for all team members to receive all package updates and every discussion involving foo@packages.debian.org (where foo is a package maintained by your team). Those packages.debian.org aliases are thus a simple way to discuss between all team members interested in the given package.

To best leverage the package tracker, here's what you should do:

  1. create a team on https://tracker.debian.org/teams/

  2. put team+<team-name>@tracker.debian.org in the Maintainer field of your team packages

  3. ensure you send git commit notices to dispatch@tracker.debian.org (the source package name will be inferred from the name of git repository, if that's not desirable, you can be explicit about the source package name by sending them to dispatch+<source-package-name>_vcs@tracker.debian.org instead).

  4. ask your team members to join the team on https://tracker.debian.org/teams/<team-name>/

Note that if you are maintaining a single package, then a team is not needed. You might want to put <source-package-name>@packages.debian.org as maintainer field and use direct package subscription (instead of team subscription).

See also the distro tracker email interface documentation for more details.

Note that team+<team-name>@tracker.debian.org doesn't offer any public mail archive yet (see https://salsa.debian.org/qa/distro-tracker/issues/14).

gitlab notifications

In Gitlab, anyone can subscribe to different notifications for changes in a repository (New note, New issue, Reopen issue, Close issue, Reassign issue, New merge request, Reopen merge request, Close merge request, Reassign merge request Merge merge request, Failed pipeline, Successful pipeline). Use the dropdown "Watch" button on each project to configure this.

Note that this feature does not offer any way to get direct commit notifications.

Import members of a team

It is not possible to transfer the members of an Alioth team to Salsa. You will need to ask the members of your team to join your team on Salsa individually.

Host project web pages

See Salsa/Doc#Web_page_hosting.

Share a group with all Debian developers

On Alioth, some repositories were configured in such a way that all Debian developers had automatically write access regardless of their membership to the corresponding Alioth team. It is possible to do the same on Salsa by sharing a project with the Debian group, which contains all debian developers as members.

To achieve that, go to the page of the project, and under Settings -> Members, there is a tab "Share with group". Select the group Debian.

Note that doing so will clutter the list of groups of all Debian developers (see https://gitlab.com/gitlab-org/gitlab-ce/issues/43397). Also this operation is not so easy to script compared to the rest (see https://lists.debian.org/debian-perl/2018/01/msg00045.html and https://salsa.debian.org/mehdi/salsa-scripts/issues/5).

Setting Alioth git repo read-only

You can set the Alioth git repository read-only by adding a pre-receive hook.