How to contribute: help us help you

[ghost]

The problem(s)

Which files do I edit?

if you are familiar with CSS look at the issues tagged with design tag.

This is the only clear thing I will know to edit: CSS files. For content and bugs, I don't know where to start. There's no overview of the technologies used or how they are used. Is there a static site generator? Are things just loaded into a public_html directory and served using CGI scripts?
If there's a problem, I probably have to find out first what we're using to then investigate which component could be failing, to then how it's failing and what can be done to resolve the issue. If everybody, individually first has to figure out what's being used, it takes away valuable time from the individual that they could have spent on the next step.

nix requirement

The README.md just provides a block on how to run the homepage with live-reload.

README

but in order to run it, I need nix. Were I just a passerby who saw a CSS error or a content error, I'd have to spend a good chunk of time first installing everything to just contribute minor changes. Especially for content, requiring more than an editor seems like overkill to me.

In my case, I'm still testing nixOS on another computer that doesn't have all my secrets, so booting that up just to contribute is pretty meh.

Suggestions

List the technologies used

Helps save time for contributors: they'll know which competencies to have in order to contribute to a certain aspect of the project.
The CSS line is a good start, but content and bugs definitely need more information.

I shouldn't have to read a bunch of different files to try and find out what this .tt extension is and what possibilities it provides (still don't know what it actually is and if I can get syntax highlighting for it).

A nix-less contribution flow

Since I don't know which technologies are used, I'm assuming the site is a generated, static one.

It would be nice to be able to "just" clone the repo, make edits, push them and see them somewhere. Github actions should allow that pretty easily if I'm not mistaken.

Overview of how things work together

As stated in Problems>"Which files do I edit?", it really helps to at least know which files are for what. Having an overview of how they are connected together is a nice to have, but definitely possible because Github supports Mermaid diagrams.

As a first step, it might even be just enough to have README.mds in the various folders

Knowing as a contributor for example "I want to edit content on the page with that guide on how to setup an environment, I go to /content/guides/environment_setup.tt" reduces searching time so much!

CONTRIBUTING.md (optional)

Maybe this is a personal preference, but the README.md can become a bit cluttered, so moving out in-depth or further information to a dedicated document makes sense to me 🤷

---

Related issues: #671

[fricklerhandwerk]

@LoveIsGrief Thanks for collecting these considerations.

It would be nice to be able to "just" clone the repo, make edits, push them and see them somewhere. Github actions should allow that pretty easily if I'm not mistaken.

That is exacly what the nix-shell invocation in the README allows you to do, locally. The very point of Nix is not to manually acquire any knowlede about tooling to make that happen.

It is something else that finding the right place to edit is hard, and the other things you mention are absolutely reasonable.

Would you mind just opening a PR, simply adding information to the README that you found while browsing? One thing I can easily imagine is annotating the output of tree -L 1 for each directory in a per-directory README.md and linking accordingly. Just annotate as much as you see fit and imagine yourself being able to handle in one go. Merging even an incremental change is already an improvement.

Skimming the makefile I found that .tt files are processed with tpage, which is a template processor written in Perl. This is something you can already add to the README.

[garbas]

The problem(s)

Which files do I edit?

if you are familiar with CSS look at the issues tagged with design tag.

This is the only clear thing I will know to edit: CSS files. For content and bugs, I don't know where to start. There's no overview of the technologies used or how they are used. Is there a static site generator? Are things just loaded into a public_html directory and served using CGI scripts? If there's a problem, I probably have to find out first what we're using to then investigate which component could be failing, to then how it's failing and what can be done to resolve the issue. If everybody, individually first has to figure out what's being used, it takes away valuable time from the individual that they could have spent on the next step.

Yes we don't have any contribution guide at this point.

The README.md just provides a block on how to run the homepage with live-reload.

The last paragraph in the section you are mentioning is pointing towards nix-build.

Before creating a pull request make sure that `nix-build` runs successfully.

It is true we don't explicitly mention that nix-build will build a website for you, but that is kinda assumed in nix projects. But lets fix the description that would make it obvious also for those who are not familiar with nix projects. I guess we can change that to :

Before creating a pull request make sure that you can build static website by running `nix-build`. The website should be present in `./result` folder. 

Would above explanation be more understandable?

but in order to run it, I need nix. Were I just a passerby who saw a CSS error or a content error, I'd have to spend a good chunk of time first installing everything to just contribute minor changes. Especially for content, requiring more than an editor seems like overkill to me.

Yes, Nix is needed. It is not possible to just edit CSS files (we use less) and bunch of other tools. Nix is the most convenient way to have this setup reproducible and maintainable. Plus we are talking about Nix on nixos.org :)

In my case, I'm still testing nixOS on another computer that doesn't have all my secrets, so booting that up just to contribute is pretty meh.

You don't need NixOS to run work on the website. You only need Nix. You can even use Nix via docker if that is your thing.

List the technologies used

Helps save time for contributors: they'll know which competencies to have in order to contribute to a certain aspect of the project. The CSS line is a good start, but content and bugs definitely need more information.

I shouldn't have to read a bunch of different files to try and find out what this .tt extension is and what possibilities it provides (still don't know what it actually is and if I can get syntax highlighting for it).

Some sort of overview would be nice, but we are waiting until we switch to some other static site generator (once some other issues are solved).

A nix-less contribution flow

Nix is a key component in this setup. What ever future technology we are going to use the requirement that it needs to support nix is a must.

Since I don't know which technologies are used, I'm assuming the site is a generated, static one.

It would be nice to be able to "just" clone the repo, make edits, push them and see them somewhere. Github actions should allow that pretty easily if I'm not mistaken.

This is already the case. If you look at the existing workflow files you will see that the preview will be generated for PRs coming from the same repo. For historical reasons we didn't yet enable for other PRs. But we should (and we will).

Overview of how things work together

As stated in Problems>"Which files do I edit?", it really helps to at least know which files are for what. Having an overview of how they are connected together is a nice to have, but definitely possible because Github supports Mermaid diagrams.

As a first step, it might even be just enough to have README.mds in the various folders

Knowing as a contributor for example "I want to edit content on the page with that guide on how to setup an environment, I go to /content/guides/environment_setup.tt" reduces searching time so much!

Currently the Makefile and flake.nix provide this information. As said before more information how things are organized will be provided when we reorganize this repository. I know currently is not ideal, but until we figure out few other things we will keep using it.

CONTRIBUTING.md (optional)

Maybe this is a personal preference, but the README.md can become a bit cluttered, so moving out in-depth or further information to a dedicated document makes sense to me shrug

👍 Once we have more information a dedicated document would make sense.