Merge pull request #2 from nix-open-org/document-more

Document more

.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  xrefcheck:
+    name: Check references
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: serokell/xrefcheck-action@v1
+
+# TODO: Use https://github.com/marketplace/actions/github-codeowners-validator

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contribution guidelines
+
+This repository generally doesn't need to follow any specific structure.
+Organic evolution of the structure is encouraged.
+
+Most importantly, the information in this repository should be kept up-to-date with the state of reality.
+Thus, all organisational changes tracked in this repository should be proposed with a PR,
+and the changes should only to be implemented when the PR is merged.
+This may be done manually (e.g. by the person merging the PR) or automatically (e.g. using CD).
+
+All files should have at least somebody in charge of keeping it up-to-date, which should be described with an entry in [CODEOWNERS](./.github/CODEOWNERS). Those people will be requested for a review and be given write access to the repository, see also [permissions of this repository](./doc/org-repo.md).
+
+## Regular manual reviews
+
+Unavoidibly it can also happen for reality to deviate from the documentation without a PR.
+To mitigate this, all people with [code owner entries](./.github/CODEOWNERS) must regularly review their files.
+This is done by [automatically opening an issue every month](./.github/workflows/review.yml) to ping all code owners.
+
+This serves as an initial fallback, but more automatic approaches could be implemented in the future, e.g. by scraping and comparing the state.

README.md

@@ -11,22 +11,16 @@ More detailed organisational documentation can be delegated to other resources.
 The goal of this repository is to make organisation transparent, explicit, discoverable and open to change.
 Anybody is welcome to open issues/PRs to add/update documentation or propose organisational changes.
 
-## Contribution guidelines
-
-This repository generally doesn't need to follow any specific structure.
-Organic evolution of the structure is encouraged.
-
-Most importantly, the information in this repository should be kept up-to-date with the state of reality.
-Thus, all organisational changes tracked in this repository should be proposed with a PR,
-and the changes should only to be implemented when the PR is merged.
-This may be done manually (e.g. by the person merging the PR) or automatically (e.g. using CD).
-
-All files should have at least somebody in charge of keeping it up-to-date, which should be described with an entry in [CODEOWNERS](./github/CODEOWNERS). Those people will be requested for a review and be given write access to the repository, see also [permissions of this repository](./org-repo.md).
-
-## Regular manual reviews
-
-Unavoidibly it can also happen for reality to deviate from the documentation without a PR.
-To mitigate this, all people with [code owner entries](./.github/CODEOWNERS) must regularly review their files.
-This is done by [automatically opening an issue every month](./.github/workflows/review.yml) to ping all code owners.
-
-This serves as an initial fallback, but more automatic approaches could be implemented in the future, e.g. by scraping and comparing the state.
+For contributing see [here](./CONTRIBUTING.md).
+
+## Overview
+
+- [Org repo](./doc/org-repo.md)
+- [Discourse](./doc/discourse.md)
+- [GitHub](./doc/github.md)
+- [Matrix](./doc/matrix.md)
+- [Moderation](./doc/moderation.md)
+- [NixOS releases](./doc/nixos-releases.md)
+- [Resources](./doc/resources.md)
+- [RFCs](./doc/rfcs.md)
+- [Teams](./doc/teams.md)

doc/discourse.md

@@ -0,0 +1,8 @@
+# Discourse
+
+The [NixOS Discourse instance](https://discourse.nixos.org/) is one of the primary communication platforms for the Nix community.
+
+That subdomain is hosted by [Flying Circus](https://flyingcircus.io/)
+
+To request permissions or changes to Discourse, talk to one of the [administrators](https://discourse.nixos.org/about).
+

doc/github.md

@@ -0,0 +1,59 @@
+# GitHub
+
+The [NixOS GitHub organisation](https://github.com/nixos) and all its repositories is part of the [official resources](./resources.md).
+
+A very small number of people are owners of this GitHub Organisation, and have ultimate permissions over it.
+
+Over 200 people in the organisation have permissions over only certain parts.
+
+## Repositories
+
+There are many repositories, but these are some of the most important ones.
+
+### [nixpkgs](https://github.com/nixos/nixpkgs/)
+
+The Nix package collection and NixOS.
+
+There are over 200 Nixpkgs committers with access to merge any PR.
+To become a Nixpkgs committer, you can apply [in this issue](https://github.com/NixOS/nixpkgs/issues/50105).
+
+Furthermore, every [Nixpkgs maintainer](https://github.com/NixOS/nixpkgs/tree/master/maintainers) is part of the organisation, such that they can be requested as a reviewer.
+
+Being a Nixpkgs maintainer doesn't grant any permissions by itself.
+They can however make use of the [Nixpkgs merge bot](https://github.com/NixOS/nixpkgs-merge-bot) in certain cases.
+
+### [nix](https://github.com/NixOS/nix)
+
+The Nix language and CLI implementation.
+
+The [Nix Team](https://nixos.org/community/teams/nix/) controls this repository.
+
+### [nixos-homepage](https://github.com/nixos/nixos-homepage)
+
+The source for the https://nixos.org/ landing page.
+
+This is primarily maintained by the [marketing team](https://nixos.org/community/teams/marketing/).
+
+### [nix.dev](https://github.com/NixOS/nix.dev)
+
+The source for https://nix.dev.
+
+The [documentation team](https://nixos.org/community/teams/documentation/) controls this repository.
+
+### [rfcs](https://github.com/NixOS/rfcs)
+
+The Nix community RFCs, see also [here](./rfcs.md).
+
+The [RFC Steering Committee](https://nixos.org/community/teams/rfc-steering-committee/) controls this repository.
+
+### [infra](https://github.com/nixos/infra)
+
+Infrastructure configuration.
+
+The [infrastructure team](https://nixos.org/community/teams/infrastructure) controls this repository.
+
+### [foundation](https://github.com/NixOS/foundation)
+
+The home of the [NixOS foundation](./resources.md#foundation).
+
+The [NixOS foundation board](https://nixos.org/community/teams/foundation-board/) controls this repository.

doc/matrix.md

@@ -0,0 +1,6 @@
+# Matrix
+
+The [`nixos.org` Matrix server](https://matrix.to/#/#space:nixos.org) is the official chat platform.
+
+If you'd like a new room for a certain topic, you can discuss this is the [NixOS Matrix Discussion](https://matrix.to/#/#matrix-discussion:nixos.org) room.
+Once decided, you can make the request in the [NixOS Matrix Suggestions](https://matrix.to/#/#matrix-suggestions:nixos.org) room.

doc/moderation.md

@@ -0,0 +1,8 @@
+# Moderation
+
+All official interaction platforms are moderated by the [moderation team](https://nixos.org/community/teams/moderation/).
+
+This primarily includes:
+- [GitHub](./github.md)
+- [Discourse](./discourse.md)
+- [Matrix](./matrix.md)

doc/nixos-releases.md

@@ -0,0 +1,7 @@
+# NixOS releases
+
+Two times a year, a new stable version of NixOS (or rather, all of [Nixpkgs](https://github.com/nixos/nixpkgs/)) is released.
+
+All information about this process is available in the [Release wiki](https://nixos.github.io/release-wiki/).
+
+See also the [NixOS release team](https://nixos.org/community/teams/nixos-release/) page

org-repo.md → doc/org-repo.md

@@ -1,14 +1,12 @@
 # Organisation repo
 
-This document describes the permissions of this repository.
+This repository itself is the entry point for documentation on official resources.
 
-Everybody in the [CODEOWNERS](./.github/CODEOWNERS) file should have write permission to the repository.
+Everybody in the [CODEOWNERS](../.github/CODEOWNERS) file has write permission to this repository.
 This allows people to get automatic review requests and merge PRs for the files that concern them.
 
 TODO: Enable branch protection to require reviews by code owners.
 TODO: Ensure that all files have a code owner
 
 Furthermore, the code owners for the CODEOWNERS file should have permission to give more people write access to this repository.
 These people get requested for reviews when new people add themselves to CODEOWNERS, allowing them to give write access when merged.
-
-Furthermore, the GitHub organisation owners unavoidable have owner permission over this repository.

doc/resources.md

@@ -0,0 +1,43 @@
+# Resources
+
+These are all the official Nix resources.
+
+Currently there is no established process for how to make new official resources or make existing resources official.
+
+## Foundation
+
+The [NixOS Foundation](https://nixos.org/community/#foundation) is a registered non-profit organisation in The Netherlands.
+It supports the Nix ecosystem by handling administration, legal and financial tasks.
+It consists of the Foundation board members, more information can be seen [on their page](https://nixos.org/community/teams/foundation-board/).
+
+## Domains
+
+The primary domain is `nixos.org`, which hosts the [landing page](https://nixos.org/) ([source](https://github.com/nixos/nixos-homepage)).
+This domain also hosts various other websites and services, such as:
+- Mail server
+- [Matrix](./matrix.md)
+- [Discourse](./discourse.md)
+- [Wiki](https://wiki.nixos.org)
+- [Search](https://search.nixos.org/)
+- [Status page](https://status.nixos.org/)
+- [Hydra](https://hydra.nixos.org/)
+- [Binary cache](https://cache.nixos.org/) and [tarballs](https://tarballs.nixos.org/)
+- [Channels](https://channels.nixos.org/) and [releases](https://releases.nixos.org/)
+
+A secondary domain is `nix.dev`, which hosts [the main documentation](https://nix.dev/) ([source](https://github.com/NixOS/nix.dev)).
+
+See the [infra repository](https://github.com/nixos/infra) for more information.
+To request permissions or changes to the infrastructure, get in touch with the [infrastructure team](https://nixos.org/community/teams/infrastructure).
+
+## GitHub
+
+The [NixOS GitHub organisation](https://github.com/nixos) and all its repositories.
+See [this page](./github.md) for more information.
+
+## Other third-party accounts
+
+- [Docker](https://hub.docker.com/u/nixos)
+- [Open collective](https://opencollective.com/nixos)
+- [YouTube](https://www.youtube.com/@NixOS-Foundation)
+- [Twitter](https://twitter.com/nixos_org)
+- [Mastodon](https://chaos.social/@nixos_org)

doc/rfcs.md

@@ -0,0 +1,3 @@
+# RFC Process
+
+The Nix RFC (Request For Comments) process exists to establish wider consensus for substantial changes. See the [rfcs repository](https://github.com/NixOS/rfcs) for more information.

doc/teams.md

@@ -0,0 +1,21 @@
+# Teams
+
+Various Nix teams exist to work together.
+Teams generally have certain authority, responsibility and accountability over their resources.
+There are currently no strict requirements from teams.
+
+As a team you might want to have a new GitHub team, Matrix room or permissions to a repository.
+Adding a team as shown below does not automatically give you that.
+Instead see [the resources page](./resources.md).
+
+## Website
+
+The most official teams are the ones declared in the [teams section](https://nixos.org/community/#governance-teams) on the homepage. 
+
+To add a new team to this list, open a PR on the [nixos-homepage repository](https://github.com/nixos/nixos-homepage).
+
+## Nixpkgs
+
+More Nixpkgs-specific teams are declared in the [`maintainers/team-list.nix` file](https://github.com/NixOS/nixpkgs/blob/master/maintainers/team-list.nix), which can be programmatically accessed using `lib.teams`.
+
+To add a new team to this list, open a PR to change it.