diff options
| -rw-r--r-- | tutorials/index.html | 13 | ||||
| -rw-r--r-- | tutorials/organizing-projects.md | 69 |
2 files changed, 82 insertions, 0 deletions
diff --git a/tutorials/index.html b/tutorials/index.html index db7a5be..d130880 100644 --- a/tutorials/index.html +++ b/tutorials/index.html @@ -38,6 +38,19 @@ title: Tutorials </a> </div> <div class="tutorial"> + <h3 id="organizing-projects">Organizing your own projects</h3> + <p> + Ready to set up your own projects? Make sure to read this short introduction + to understand how projects are organized on SourceHut. + </p> + <a href="organizing-projects.md" class="btn btn-default"> + Read more + <span class="icon icon-caret-right"> + <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg> + </span> + </a> +</div> +<div class="tutorial"> <h3 id="getting-started-with-buildssrht">Getting started with builds.sr.ht</h3> <p> Running your first few jobs on our continuous integration platform, diff --git a/tutorials/organizing-projects.md b/tutorials/organizing-projects.md new file mode 100644 index 0000000..df8d5b3 --- /dev/null +++ b/tutorials/organizing-projects.md @@ -0,0 +1,69 @@ +--- +title: Organizing projects +--- + +One of the key features that differentiates SourceHut from many other forges is +the concept of projects as collections of arbitrary resources. This makes for a +powerful tool, but might take some getting used to if you are accustomed to +working with other forges. To help with that, this tutorial will cover the most +important aspects of organizing your projects. + +## Understanding projects + +On other forges, a project is usually implicitly equivalent to a source code +repository. A repository can for example have one issue tracker, and maybe also +one wiki. If you create a new repository, you have essentially created a new +project. + +On SourceHut, things are a little different. Projects are something you can +create and manage independently from anything else. They are managed on the +[project hub](https://sr.ht) (sometimes referred to as +[hub.sr.ht](https://man.sr.ht/hub.sr.ht/). Most importantly, creating a new +source code repository _does not create a new project_. You will have to do so +explicitly. + +Projects serve two purposes: they provide discoverability and link together +other resources. They might for example link source code repositories with bug +trackers and mailing lists. Unlike other forges, SourceHut projects do not put +any constraints on the cardinality of these links. A project can contain +multiple source code repositories, and an issue tracker can be part of several +projects. + +## Features that require projects + +Even if all you need is a single source code repository, the one thing that +only a project can provide is _discoverability_. All of SourceHut's +exploration and search features operate on projects: their description, their +[tags](https://man.sr.ht/hub.sr.ht/#best-practices-for-tags), etc. So if you +want others to be able to find your work, make sure to create a project for +it. + +SourceHut also has a bunch of cross-service features that can only work if +certain resources are linked by means of being part of the same project. Some +common examples include: + +* Referencing tickets in [commit messages](https://man.sr.ht/git.sr.ht/#referencing-tickets-in-git-commit-messages) +* Patches to mailing lists [triggering builds](https://man.sr.ht/builds.sr.ht/#hubsrht) + +All these examples use resources from different services, so to determine what +is allowed and what isn't, SourceHut relies on the project owner to link the +resources through projects. + +## Common project layouts + +To give you some sense of how projects are commonly organized, here are a few +examples: + +* [SourceHut](https://sr.ht/~sircmpwn/sourcehut/) itself is a good example of a + reasonably complex, but otherwise not unusual project: it has multiple source + code repositories, multiple mailing lists, and multiple issue trackers +* The [vim](https://sr.ht/~vim-project/vim/sources) folks maintain both a git + and a mercurial repository - both part of the same project +* Turning things around, many developers employ the concept of a [public + inbox](https://lists.sr.ht/~sircmpwn/public-inbox), a catch-all mailing list + on which they accept patches for various smaller projects, by linking the + list to each of them + +In the end, the project layout has to match _your_ needs. But the flexibility +of SourceHut's approach to projects comes with one chore: you need to think +about it, and configure it explicitly. |