doc: add contributing guide

[awwpotato]

as discussed (very briefly) in #1687

TODO:

• Add redirects from old pages
• Give headers custom names
• Possible reword some things that don't make sense now that's it one big document.

Things done

• Tested locally
• Tested in testbed
• Commit message follows commit convention
• Fits style guide
• Respects license of any existing code used

Notify maintainers

cc @danth @trueNAHO @MattSturgeon

[awwpotato]

this is what I mean by give headers custom names, documention-1 might change if we add another documention above it. it should be possible using [development-enviroment-documentation]: #development-enviroment-documentation, but I'm not sure if mdbook support this.

[MattSturgeon]

I believe mdbook does support headers that use {} annotations. The same pandoc-inspired syntax that nixpkgs uses:

## Some heading { #some-id .some-class }

This is a subset of what nixpkgs supports though, for example iirc it only works on headings; other elements cannot have {} annotations.

[MattSturgeon]

Add redirects from old pages

Agreed.

It should be simple to add the removed pages to book.toml. I believe you can redirect the page to target a specific anchor on the new page, but I'm not sure.

Give headers custom names

Good idea if any headings are particularly ambiguous. Comments below.

Possible reword some things that don't make sense now that's it one big document.

I've not reviewed the old/new text, but this may be a good idea. This shouldn't necessarily block the PR though, imo.

---

It looks like currently, you only have links to external sites and to other anchors on the same page.

If that ever changes and you end up with links to the docs, you'll likely want to have absolute URLs in your contributing file, but convert them to relative-path links when building the docs.

Nixvim solves this using a "fix links" wrapper derivation that uses pandoc.

But for now it's a non-issue afaict.

[MattSturgeon]

I believe mdbook does support headers that use {} annotations. The same pandoc-inspired syntax that nixpkgs uses:

## Some heading { #some-id .some-class }

This is a subset of what nixpkgs supports though, for example iirc it only works on headings; other elements cannot have {} annotations.

[MattSturgeon]

Suggested change

	See also: [Adding modules → Documentation](./contributing.html#documentation)
	See also: [Documentation](#documentation)

[awwpotato]

we still want the adding modules prefix, perhaps a different format to indicate it's sub-header tho?

[MattSturgeon]

we still want the adding modules prefix

I assume the link text was previously referring to a separate file, i.e. File → Heading.

So that'd now be Contributing → Documentation iiuc, which feels redundant.

I agree "Documentation" is kinda vague though, but it feels strange that it'd be the only example of using → to indicate heading→sub-heading 🫤

---

I'm happy for it to say as is if you think it still makes sense.

[MattSturgeon]

Not important or blocking, but just for the record these are the only links to the repo or to elsewhere in the docs:

[MattSturgeon]

In nixvim, we would write this as a repo-relative link:

Suggested change

	the [`/stylix/mk-target.nix`](
	https://github.com/danth/stylix/blob/-/stylix/mk-target.nix) in-source
	the [`/stylix/mk-target.nix`](
	./stylix/mk-target.nix) in-source

And our fix-links wrapper would auto-convert it to an external link when copying the file into the docs drv.

[MattSturgeon]

This isn't really important, but it'd have some subtle benefits:

• In forks, the link would stay within the fork.
• In the docs, you could link to the specific commit; like you already do for other links to stylix's repo.
• The owner would automatically be in sync with other repo links; this is still using the old repo owner.

[MattSturgeon]

Same

[MattSturgeon]

In nixvim, the fix-links wrapper would convert this to a relative link (./) when copying into the docs drv.

[trueNAHO]

It might be better to place the contibuting information at the bottom, as previously done, since most people will never read this. The more commonly used information should be at the top.

[trueNAHO]

Personally, I find the → character confusing:

Suggested change

	See also: [Adding modules → Documentation](#documentation)
	See also: [Adding modules > Documentation](#documentation)

More flowy phrasings would be:

• Suggested change

  	See also: [Adding modules → Documentation](#documentation)
  	See also the [documentation on adding modules](#documentation)
• Suggested change

  	See also: [Adding modules → Documentation](#documentation)
  	See also the ["Adding modules" documentation](#documentation)

I prefer the "documentation on adding modules" variant.

[MattSturgeon]

I prefer the "documentation on adding modules" variant.

Agreed.

[trueNAHO]

Personally, I find the → character confusing:

Suggested change

	See also: [Development environment → Documentation](#documentation-1)
	See also: [Development environment > Documentation](#documentation)

More flowy phrasings would be:

• Suggested change

  	See also: [Development environment → Documentation](#documentation-1)
  	See also the [documentation on the development environment](#documentation)
• Suggested change

  	See also: [Development environment → Documentation](#documentation-1)
  	See also the ["Development environment" documentation](#documentation)

I prefer the "documentation on the development environment" variant.