The project hub links resources like repositories, bug trackers, and mailing lists, into projects, providing a central hub for your projects' resources and a public, searchable index of projects on SourceHut.

See also:

• Installation guide

#Introduction

Unlike many other forges, projects on SourceHut are not predominantly oriented around a repository. Instead, a project is a separate concept which can have any number of repositories, mailing lists, and bug trackers, allowing you to organize both simple and complex projects. You might have a dozen git repositories and a handful of mailing lists, a bug tracker and nothing else, or any other number of configurations tailored to suit your project's needs.

The SourceHut project provides a good example of what's possible, organizing our many source repositories and mailing lists in a centralized place.

The public project index also allows you to optionally list your project among all of the other projects on SourceHut, helping users and contributors find your project and similar projects in various domains.

#Project resource integrations

The project hub provides a number of integrations which link your project's resources together.

#Referencing tickets in commits and patches

You can reference tickets on your bug trackers in your git commits and patches proposed to development mailing lists, to track the lifecycle of a change which addresses a ticket. Git commit trailers are used for this purpose.

The following keys are used to reference tickets, with the ticket URL as the trailer's value:

• References: a generic ticket reference
• Implements: this commit implements a feature defined by a ticket
• Fixes: this commit fixes a bug defined by a ticket
• Closes: this commit closes a ticket in a general sense

For example, the following commit message will close a ticket as IMPLEMENTED:

foo: add support for yaml config files

Implements: https://todo.sr.ht/~arkanoid/foobar/1337
Signed-off-by: John Doe <john@doe.io>

#Testing patches sent to development lists

When you send a patch to a development list associated with a project on the project hub, the project hub will submit a build job to test that change and reply to the email thread with the build results.

Patches are associated with source repositories via the subject prefix, which must match the name of a repository on the same project as the mailing list. For example, if you have a git repository on your project named "foobar", patches sent with the subject "[PATCH foobar] ..." will be tested against that repository.

The default subject prefix for a git repository may be configured like so:

git config format.subjectPrefix 'PATCH project-name'

Note that builds submitted in this way have secrets disabled.

#Build environment

The following variables will be set in the submitted build's environment:

• BUILD_SUBMITTER: hub.sr.ht
• BUILD_REASON: patchset
• PATCHSET_ID: ID of the patchset (e.g. 20273)
• PATCHSET_URL: link to the patchset (e.g. https://lists.sr.ht/~sircmpwn/sr.ht-dev/patches/20273)

#Disabling the integration

If you don't want to test patches in this manner, you can disable this integration in your build manifest:

submitter:
  hub.sr.ht:
    enabled: false

#Best practices for #tags

Tags aid in community building and project discovery. If we are consistent about how we use them, it will help meet those goals better. Here are some recommendations for your project tags:

• Avoid adding tags for implementation language unless it matters (e.g. language-specific libraries)
• Avoid adding tags for platform support unless your project is based on platform-specific features (e.g. seccomp-related projects should use #linux)
• If there are multiple ways to word a tag (e.g. #gfx vs #graphics), check if there's already an existing preference you can join