From 6ba43ec90a1130e14828551bc88f0b57fbb6f15c Mon Sep 17 00:00:00 2001 From: zowoq <59103226+zowoq@users.noreply.github.com> Date: Wed, 26 Apr 2023 16:19:18 +1000 Subject: [PATCH] switch to mkdocs --- README.md | 83 +------------------ docs/README.md | 62 -------------- docs/_config.yml | 26 ------ docs/administrators.md | 27 ++++++ .../README.md => docs/community-builder.md | 4 +- docs/contact.md | 7 ++ docs/faq.md | 20 +++++ docs/index.md | 28 +++++++ docs/services.md | 46 ++++++++++ flake.nix | 16 +++- mkdocs.yml | 35 ++++++++ shell.nix | 1 + 12 files changed, 182 insertions(+), 173 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/_config.yml create mode 100644 docs/administrators.md rename roles/builder/README.md => docs/community-builder.md (81%) create mode 100644 docs/contact.md create mode 100644 docs/faq.md create mode 100644 docs/index.md create mode 100644 docs/services.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index d213970ba..2370bb314 100644 --- a/README.md +++ b/README.md @@ -2,87 +2,6 @@ Welcome to the Nix Community infrastructure project. This project holds all the NixOS and Terraform configuration for this organization. -## Services - -### `Community builder` - build01.nix-community.org - -We provide an x86 build machine as a public remote builder for the nix community, this machine also has an aarch64 machine configured as its own remote builder. - -See [here](roles/builder/README.md) for more information. - -### `Continuous integration` - -We provide x86 and aarch64 linux CI via these systems: - -- `Hercules` - https://hercules-ci.com/github/nix-community - - - To enable hercules builds go to `https://hercules-ci.com/github/nix-community/$REPO` and click "Build this repository". - -- `Hydra` - https://hydra.nix-community.org - - - To enable hydra builds add a new project in this [file](terraform/hydra-projects.tf). - -### `Cache` - https://nix-community.cachix.org/ - -All of the above CI builds are pushed to the cache. - -Thanks to Cachix for sponsoring our binary cache! - -### `Search` - https://search.nix-community.org - -Hound code search for NixOS and nix-community GitHub organisations. - -### `nix-community.org DNS` - -DNS is managed by terraform in this [file](terraform/cloudflare_nix-community_org.tf). - -### `ryantm-updater bot` - -- Docs: https://ryantm.github.io/nixpkgs-update -- Logs: https://r.ryantm.com/log/ - -### `nur-update` - -## Support - -For urgent matters, create an issue here: [New Issue](https://github.com/nix-community/infra/issues/new). - -For repo additions, service requests and general conversation about governance and direction of the project, use the [Discussion forum](https://github.com/orgs/nix-community/discussions). - -For casual chat, come join us in the [nix-community](https://matrix.to/#/#nix-community:nixos.org) room. - -The admins can also be contacted via [admin@nix-community.org](mailto:admin@nix-community.org), email sent to this address will be forwarded to all of the admins. - -### nix-community administrators - -- [@Mic92](https://github.com/Mic92) -- [@adisbladis](https://github.com/adisbladis) -- [@ryantm](https://github.com/ryantm) -- [@zimbatm](https://github.com/zimbatm) -- [@zowoq](https://github.com/zowoq) - -#### Role - -The role of the administrators is to support the members of the org, and the Nix project in general. - -#### Responsibilities - -The administrators are responsible for serving the community to the best of their ability and availability. - -They provide services such as: - -- keep the systems updated and patched -- reply to user requests -- host new services that could help the project -- on-board new projects -- resolve conflict - -The administrators are the only "owners" of the github organization. - -#### Quorum of 5 rule - -To reduce the attack surface on the project, the administrative team size is limited to 5 people. - -## Hosts +You're probably looking for our website [https://nix-community.org](https://nix-community.org). See [HOSTS.md](HOSTS.md), this file also contains deployment details. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 2297e6b6f..000000000 --- a/docs/README.md +++ /dev/null @@ -1,62 +0,0 @@ -Nix community - -@nix-community is a GitHub organization that works alongside the @NixOS organization. - -The @NixOS organization holds all the mission-critical projects such as Nix, Nixpkgs, NixOps, Hydra, etc. - -The @nix-community organization is the community playground. We don't need to be as strict with permissions. The org can host any projects that benefit from a shared ownership. We provide infrastructure and support for those projects as well as visibility. - -## Infrastructure - -To support our activities we have a little bit of infrastructure in place. - -See https://github.com/nix-community/infra for the list of services and configuration. - -## FAQ - -### How do I get my project included? - -Ideally the type of projects that are accepted have some level of maturity and can benefit from a shared ownership. The goal is to have as much projects maintained and not for the org to become a graveyard. - -We don't have a strict procedure. For now, ping one of the [nix-community administrators](#nix-community-administrators). - -### What are the rules of engagement? - -The Nix community is nice. Be nice! Typically this means: - -1. Argument on technical details, not the people. -2. Give the benefit of the doubt as much as possible. We all have different lives with different backgrounds. -3. Keep in mind that all the work here is done by volunteers. -4. :) - -Nothing is set in stone. Think of these as the guidelines for our interactions. - -The maintainer of a project gets admin access to the project they maintain. The maintainer can request that more people be invited into the org so they can join their projects team. - -If you see a project that is under-maintained, submit PRs to fix it as if it was your own project. If the PRs don't get merged, ping the [nix-community administrators](#nix-community-administrators). - -## Support - -For urgent matters, create an issue here: [New Issue](https://github.com/nix-community/infra/issues/new). - -For repo additions, service requests and general conversation about governance and direction of the project, use the [Discussion forum](https://github.com/orgs/nix-community/discussions). - -For casual chat, come join us in the [nix-community](https://matrix.to/#/#nix-community:nixos.org) room. - -## nix-community administrators - -If you need to contact the nix-community admins, they are listed [here](https://github.com/nix-community/infra#nix-community-administrators). - -## Sponsors - -Thanks to all our sponsors. - - -|[Cachix](https://cachix.org)| -|:-:| -|Cachix provides us with 1TB of free cache.| - -|[Gandi](https://www.gandi.net/)| -|:-:| -|Gandi provides us with a free domain and a virtual private server.| - diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 77fdd3b41..000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,26 +0,0 @@ -theme: jekyll-theme-primer -url: "https://nix-community.org" -title: nix-community -description: "" - -# see https://github.com/github/pages-gem/blob/754a725e4766d4329bb1dd0e07c638a045ad2c04/lib/github-pages/plugins.rb#L6-L42 -plugins: - - jemoji - - jekyll-avatar - - jekyll-default-layout - - jekyll-feed - - jekyll-mentions - - jekyll-readme-index - - jekyll-sitemap - -markdown: CommonMarkGhPages -# see https://github.com/gjtorikian/commonmarker#parse-options -commonmark: - options: - - FOOTNOTES - - SMART - - UNSAFE - extensions: - - autolink - - strikethrough - - table diff --git a/docs/administrators.md b/docs/administrators.md new file mode 100644 index 000000000..1ee44096d --- /dev/null +++ b/docs/administrators.md @@ -0,0 +1,27 @@ +- [@Mic92](https://github.com/Mic92) +- [@adisbladis](https://github.com/adisbladis) +- [@ryantm](https://github.com/ryantm) +- [@zimbatm](https://github.com/zimbatm) +- [@zowoq](https://github.com/zowoq) + +#### Role + +The role of the administrators is to support the members of the org, and the Nix project in general. + +#### Responsibilities + +The administrators are responsible for serving the community to the best of their ability and availability. + +They provide services such as: + +- keep the systems updated and patched +- reply to user requests +- host new services that could help the project +- on-board new projects +- resolve conflict + +The administrators are the only "owners" of the github organization. + +#### Quorum of 5 rule + +To reduce the attack surface on the project, the administrative team size is limited to 5 people. diff --git a/roles/builder/README.md b/docs/community-builder.md similarity index 81% rename from roles/builder/README.md rename to docs/community-builder.md index e6258ba18..aeae8f6f0 100644 --- a/roles/builder/README.md +++ b/docs/community-builder.md @@ -1,6 +1,6 @@ -## Community builder +### Access -If you want access read the security guide lines on [aarch64-build-box](https://github.com/nix-community/aarch64-build-box). Than add your username to [`roles/builder/users.nix`](users.nix). Don't keep any important data in your home! We will regularly delete `/home` without further notice. +If you want access read the security guide lines on [aarch64-build-box](https://github.com/nix-community/aarch64-build-box). Than add your username to [`roles/builder/users.nix`](https://github.com/nix-community/infra/blob/master/roles/builder/users.nix). Don't keep any important data in your home! We will regularly delete `/home` without further notice. ### Using your NixOS home-manager configuration on the hosts diff --git a/docs/contact.md b/docs/contact.md new file mode 100644 index 000000000..fa3c30cca --- /dev/null +++ b/docs/contact.md @@ -0,0 +1,7 @@ +For urgent matters, create an issue here: [New Issue](https://github.com/nix-community/infra/issues/new). + +For repo additions, service requests and general conversation about governance and direction of the project, use the [Discussion forum](https://github.com/orgs/nix-community/discussions). + +For casual chat, come join us in the [nix-community](https://matrix.to/#/#nix-community:nixos.org) room. + +The admins can also be contacted via [admin@nix-community.org](mailto:admin@nix-community.org), email sent to this address will be forwarded to all of the admins. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..a89ab05ad --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,20 @@ +### How do I get my project included? + +Ideally the type of projects that are accepted have some level of maturity and can benefit from a shared ownership. The goal is to have as much projects maintained and not for the org to become a graveyard. + +We don't have a strict procedure. For now, ping one of the [nix-community administrators](./administrators.md). + +### What are the rules of engagement? + +The Nix community is nice. Be nice! Typically this means: + +1. Argument on technical details, not the people. +2. Give the benefit of the doubt as much as possible. We all have different lives with different backgrounds. +3. Keep in mind that all the work here is done by volunteers. +4. :) + +Nothing is set in stone. Think of these as the guidelines for our interactions. + +The maintainer of a project gets admin access to the project they maintain. The maintainer can request that more people be invited into the org so they can join their projects team. + +If you see a project that is under-maintained, submit PRs to fix it as if it was your own project. If the PRs don't get merged, ping the [nix-community administrators](./administrators.md). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..b698ff738 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,28 @@ +[nix-community]: https://github.com/nix-community +[NixOS]: https://github.com/NixOS + +Nix community + +[@nix-community][nix-community] is a GitHub organization that works alongside the [@NixOS][NixOS] organization. + +The [@NixOS][NixOS] organization holds all the mission-critical projects such as Nix, Nixpkgs, NixOps, Hydra, etc. + +The [@nix-community][nix-community] organization is the community playground. We don't need to be as strict with permissions. The org can host any projects that benefit from a shared ownership. We provide infrastructure and support for those projects as well as visibility. + +## Infrastructure and services + +To support our activities we have a little bit of infrastructure in place, see [services](./services.md). The configuration is kept in [nix-community/infra](https://github.com/nix-community/infra). + +## Sponsors + +Thanks to all our sponsors. + + +|[Cachix](https://cachix.org)| +|:-:| +|Cachix provides us with 1TB of free cache.| + +|[Gandi](https://www.gandi.net/)| +|:-:| +|Gandi provides us with a free domain and a virtual private server.| + diff --git a/docs/services.md b/docs/services.md new file mode 100644 index 000000000..073edd6ab --- /dev/null +++ b/docs/services.md @@ -0,0 +1,46 @@ +## Community builder + +We provide an x86 build machine (`build01.nix-community.org`) as a public remote builder for the nix community, this machine also has an aarch64 machine configured as its own remote builder. + +See [here](./community-builder.md) for more information. + +## Continuous integration + +We provide x86_64 and aarch64 linux CI via these systems: + +#### Hercules + +[https://hercules-ci.com/github/nix-community](https://hercules-ci.com/github/nix-community) + +To enable hercules builds go to `https://hercules-ci.com/github/nix-community/$REPO` and click "Build this repository". + +#### Hydra + +[https://hydra.nix-community.org](https://hydra.nix-community.org) + +To enable hydra builds add a new project in this [file](https://github.com/nix-community/infra/blob/master/terraform/hydra-projects.tf). + +## Cache + +[https://nix-community.cachix.org/](https://nix-community.cachix.org/) + +All of the above CI builds are pushed to the cache. + +## Search + +[https://search.nix-community.org](https://search.nix-community.org) + +Hound code search for NixOS and nix-community GitHub organisations. + +## nix-community.org DNS + +DNS is managed by terraform in this [file](https://github.com/nix-community/infra/blob/master/terraform/cloudflare_nix-community_org.tf). + +## ryantm-updater bot + +- Docs: [https://ryantm.github.io/nixpkgs-update](https://ryantm.github.io/nixpkgs-update) +- Logs: [https://r.ryantm.com/log/](https://r.ryantm.com/log/) + +## nur-update + +[https://github.com/nix-community/nur-update](https://github.com/nix-community/nur-update) diff --git a/flake.nix b/flake.nix index 1adf6f048..d8520e8da 100644 --- a/flake.nix +++ b/flake.nix @@ -62,7 +62,21 @@ ./shell.nix ]; - perSystem.treefmt.imports = [ ./treefmt.nix ]; + hercules-ci.github-pages.branch = "master"; + + perSystem = { config, pkgs, ... }: { + treefmt.imports = [ ./treefmt.nix ]; + + packages.pages = pkgs.runCommand "pages" + { + buildInputs = [ pkgs.python3.pkgs.mkdocs-material ]; + } '' + cp -r ${pkgs.lib.cleanSource ./.}/* . + mkdocs build --strict --site-dir $out + ''; + + hercules-ci.github-pages.settings.contents = config.packages.pages; + }; flake.nixosConfigurations = let diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..d60d2156e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,35 @@ +nav: + - Nix Community: index.md + - Services: + - services.md + - community-builder.md + - About: + - FAQ: faq.md + - administrators.md + - contact.md + +theme: + name: material + features: + - content.action.edit + - content.code.annotate + - content.tabs.link + - navigation.expand + - navigation.instant + - navigation.tabs + - navigation.tracking + favicon: nix-community-logo.png + logo: nix-community-logo.png + icon: + repo: fontawesome/brands/github + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/nix-community + +site_name: Nix Community +site_url: https://nix-community.org +copyright: Copyright © 2023 Nix community projects +repo_name: "nix-community/infra" +repo_url: https://github.com/nix-community/infra diff --git a/shell.nix b/shell.nix index bd9087833..325eca88d 100644 --- a/shell.nix +++ b/shell.nix @@ -14,6 +14,7 @@ ] )) rsync + config.packages.pages.buildInputs config.treefmt.build.wrapper ]; };