Hopefully addresses the common pitfall amongst new users that is the
creation of projects and their usage.

Signed-off-by: Conrad Hoffmann <ch@bitfehler.net>
---
Any feedback welcome, especially from new(-ish) users!

 tutorials/index.html             | 13 ++++++
 tutorials/organizing-projects.md | 69 ++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 tutorials/organizing-projects.md

diff --git a/tutorials/index.html b/tutorials/index.html
index db7a5be..d130880 100644
--- a/tutorials/index.html
+++ b/tutorials/index.html
@@ -37,6 +37,19 @@ title: Tutorials
     </span>
   </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>
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. 
-- 
2.42.0

I think it's cool that you thought of documenting this! At the same
time, I think a tutorial, while nice, is not the solution. I shouldn't
have to read a tutorial to know how to use the website. The biggest
problem with projects currently is that the UI is just very confusing.
It's not at all clear what thing is part of which project, what kinds of
things can be part of a project, and how to navigate between different
things within a project.

Another thing that never made sense to me personally is having to decide
whether to create a project or not for each repository. If I only have a
git repository (no tracker etc.), what's the point in _also_ creating a
project for that repository? I've heard the argument that it somehow
gives the project a visible home, but it's practically indistinguishable
from just having a repo.

Just an idea: perhaps repositories and projects could be merged. Then, I
could just add an issue tracker to one or more repositories. Linked
repositories and issue trackers would then have navigation buttons to
each other. The only downside of this that I can see is that you
couldn't have a project that _both_ (1) has no repository, _and_ (2) has
two or more things in it, such as an issue tracker and a mailing list.
But how common is this use-case really, and is it worth having a
confusing project/repo distinction just for this use case's sake?

(Or, perhaps most simply, you can just associate anything to anything.
An issue tracker and a mailing list can be linked; so can a repository
and a mailing list. There is no central page connecting them. Rather,
all resources have navigation links; for example, a mailing list has a
way to navigate to “things linked to this mailing list”. This approach
would be the most flexible, but still probably unnecessarily so — most
work happens around a repository after all.)

On Monday, 4 September 2023 17:15:07 CEST Conrad Hoffmann wrote:
> Hopefully addresses the common pitfall amongst new users that is the
> creation of projects and their usage.
>  ...
> 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

I'm not sure what the goal of this tutorial is. Depending on that, my 
recommendation goes two (very) different ways.
1. How to convert from a Forgejo/GitLab/GitHub project to a SourceHut one
2. Introduction to SourceHut projects

ad 1) Use my description as 'title'
The current text seems to reflect this 'perspective'

ad 2) This is what I _think_ you actually wanted to do/describe
I can ofc be completely wrong on that ;-)

A SourceHut project is already an organizational 'thing', so I would just name 
it projects, but 'SourceHut projects' may be better as 'project' is very 
generic already and this document talks (mostly) about the differences with 
_other_ (type of) projects.

If my assumption is correct, then I'd recommend to restructure the document.

Something like this:
- What is a SourceHut project* and what is it good for? Describe it as 'its 
own thing' and not for a person who first has to unlearn the 'old' way of doing 
things.
- How to use SourceHut projects (examples do wonders)
- How it is different from other 'code hosting' providers (so end with this, 
not start with it)

*) I find the 'New Project Wizard' actually very good at (self-)explaining SH 
projects. It asks whether you want to add an existing or a new code repo and 
after that whether you want to add *another* one. And it suggest to add one or 
more other things you may want to have in a project (ML/TODO/etc)

> +One of the key features that differentiates SourceHut from many other
> forges is +the concept of projects as collections of arbitrary resources.

You may want to explain and/or give example of 'forges' as I wouldn't expect 
everyone/newbies to be familiar with that term.

> +## Understanding projects
> +
> +On other forges, a project is usually implicitly equivalent to a source

s/.../A SourceHut project is its own 'thing ' with which you can ...

Poor wording on my part, but I'd recommend to not start with a comparison to 
other forges which the user may not have any experience with.

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

This is (a bit) confusing as I think you meant project on 'those other forges' 
here? Make it (very) clear when you're talking about a SourceHut project or a 
non-SourceHut 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.

It looks like I learned something new: a hub is not a synonym for (SH) 
project, but it's also its own thing. I first thought that it was a thing 
'above' SH-projects, but now I'm not so sure ...

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

Definitely show that you/SH is eating their own dog-food, but may use this as 
the last example and start with a simple(r) one?

In general it may be a good idea why you think a linked project is a good 
example.

> +* The [vim](https://sr.ht/~vim-project/vim/sources) folks
> maintain both a git +  and a mercurial repository - both part of the same
> project

Vim is ofc awesome, but I initially thought that it was actually a poor 
example for the project feature as it only has code repos, but none of the 
other things you can add to a project.
I later thought that one can see that as an actual feature, but it may not be 
obvious to most.

There was a recent discussion (on debian-project ML) about putting all the 
Debian packaging repos on Debian's Salsa (GitLab instance).
(At least?) One person wasn't adverse to that, but they didn't want to accept 
PRs/MRs on it. Or give the impression that it was possible (apparently you 
can't turn of PRs on GH).
Or have any of the other features often available in forges.
Just a read-only repo which you can (git) clone.

> +* 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

I'm aware of the feature, but I'm not so sure this is a good example of the 
project feature? I know you can add it as a/the ML to a project, but it's not 
a project (in and of) itself?

> +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.

s/to think about it, and//
(Which can also be a feature, see my comments wrt Vim)

HTH,
  Diederik

Hi Diederik,

thanks for the detailed feedback! I'll refrain from the quoting dance to 
keep this legible, but to sum it up:

Totally agree that I went a bit off the rails with regards to comparison 
with other forges. The folks who do come from GitHub/GitLab/whatever are 
a main target group, but basing this solely on comparison does indeed 
not make for a nice tutorial.

I'll restructure the document accordingly and also elaborate on the 
examples a bit, and it's proabably worth mentioning the "wizard" as well.

Cheers,
Conrad

Hi Vlad,

On 9/4/23 17:51, Vlad-Stefan Harbuz wrote:
> I think it's cool that you thought of documenting this! At the same
> time, I think a tutorial, while nice, is not the solution. I shouldn't
> have to read a tutorial to know how to use the website. The biggest
> problem with projects currently is that the UI is just very confusing.
> It's not at all clear what thing is part of which project, what kinds of
> things can be part of a project, and how to navigate between different
> things within a project.

I think we all agree that there is much to be improved in the UI. I 
think this will come once the dust has settled on the GraphQL 
federation. That said, even a good UI in my opinion does not obviate the 
need for documentation for those folks who like it and, if nothing else, 
for us to link to when someone asks about it :)

> Another thing that never made sense to me personally is having to decide
> whether to create a project or not for each repository. If I only have a
> git repository (no tracker etc.), what's the point in _also_ creating a
> project for that repository? I've heard the argument that it somehow
> gives the project a visible home, but it's practically indistinguishable
> from just having a repo.

I'd say in a case where it is indistinguishable to you, you likely don't 
need a project :)

> Just an idea: perhaps repositories and projects could be merged. Then, I
> could just add an issue tracker to one or more repositories. Linked
> repositories and issue trackers would then have navigation buttons to
> each other. The only downside of this that I can see is that you
> couldn't have a project that _both_ (1) has no repository, _and_ (2) has
> two or more things in it, such as an issue tracker and a mailing list.
> But how common is this use-case really, and is it worth having a
> confusing project/repo distinction just for this use case's sake?

And from the follow-up:

> (Or, perhaps most simply, you can just associate anything to anything.
> An issue tracker and a mailing list can be linked; so can a repository
> and a mailing list. There is no central page connecting them. Rather,
> all resources have navigation links; for example, a mailing list has a
> way to navigate to “things linked to this mailing list”. This approach
> would be the most flexible, but still probably unnecessarily so — most
> work happens around a repository after all.)

The "navigation buttons to each other" will come, regardless of how it's 
implemented (see above). And while I understand that "simply link x to 
y" sounds appealing, at some point we'll also have to talk about 
implementation. And having all services know about each other is not a 
viable interface. Currently, the project hub coordinates it all. And 
creating projects implicitly is in my opinion bound to make things even 
more confusing for folk who do need any but the most basic use cases.

Also, honestly, I don't see any chance of this basic architecture being 
overthrown. There is, however, a lot of leeway in how the UI will be 
updated after GQL federation. It would be great to get your feedback 
then, as I think a good UI can at least cover up a whole lot of 
inevitable implementation details.

Cheers,
Conrad

Thanks!

To git@git.sr.ht:~sircmpwn/sr.ht-docs
   1652e55..b35832e  master -> master