From 935d99d85d37d090a1e72f9df32f200caeca8196 Mon Sep 17 00:00:00 2001 From: ahuston-0 Date: Thu, 8 Feb 2024 22:21:43 -0500 Subject: [PATCH] Add basic contributing guide Signed-off-by: ahuston-0 --- CONTRIBUTING.md | 3 ++ README.md | 36 +++++++++++++++++++++++ docs/CONTRIBUTING.md | 68 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 107 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 docs/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..53f572a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing + +Please see the [contributors guide](./docs/CONTRIBUTING.md) diff --git a/README.md b/README.md new file mode 100644 index 0000000..3f87277 --- /dev/null +++ b/README.md @@ -0,0 +1,36 @@ +# Nix Dotfiles + +This repository contains the flake required to build critical and personal +infrastructure running NixOS. The setup can be explored as follows. + +This repo supports `x86_64-linux` and `aarch64-linux`, and in theory supports +Mac (althought that hasn't been tested). + +## Setting Up + +Please see [our setup guide](./docs/setting-up.md) for more information on how +to onboard a new user or system. + +## Interested? + +Although we are not actively looking for new members to join in on this repo, +we are not strictly opposed. Please reach out to @ahuston-0 or @RichieCahill +for further information. + +## Repo Structure + +- `keys/`: PGP public keys, for those who are using `SOPS` for secrets +- `modules/`: Nix modules created by us for common services or overrides +(fail2ban, hydra, certain boot params, etc.) +- `systems/`: config for common *server* components, as well as per-server configurations +- `users/`: this directory has two major subdirectories, both are critical + - `users/`: includes configs for `home-manager`, `SOPS`, and `SSH` keys + , for those who use them + - `users//systems`: functions similarly to `systems/`, although for + laptops, desktops, and even a Raspberry Pi now + +## Contributing + +For members of our organization who are looking to either contribute to the +existing infrastructure, or onboard their own hardware, please see +[our contributors guide](./docs/CONTRIBUTING.md) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..10ab27d --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to nix-dotfiles + +## Preliminary info + +This repository is written using nix-flakes on nix-unstable all the way +through. We do not currently have a way to provide support for NixOS stable +releases and nor do we plan to (please open an issue if that +is a breaking issue so we can better understand your use-case). + +## Style Guide + +We do not currently have a set formatter, although work is being done to +narrow down our options. See +[our fork of the rfc-0101 repo](https://github.com/RAD-Development/rfc-0101). + +## Active Development + +To contribute to the repo, you can either ask to be provided a role +(for those who are adding machines to the repo), or fork the repo and open a PR +(for those who are making external contributions). + +Our main branch is protected (not even admins can directly push to main) and +all PRs require at least one approval. PRs which touch global files +(`flake.nix`, `modules/`, `systems/configuration.nix`, `.sops.yaml`, etc) +must have two approvals and may require more subject to the approvers discretion +(ie. a change which affect all servers or users). + +### Branching + +We use the below guide for creating branches currently. It is not necessarily +a strict standard, but if not followed will lead to questions from reviewers, +and will eventually trip a check when merging to main. + + + +| Branch Name | Use Case | +|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| main | protected branch which all machines pull from, do not try to push directly | +| feature/\ | \ is a new feature being added to the repo, for personal or common use | +| fixup/\ | \ is a non-urgent bug, PRs merging from these branches should be merged when possible, but are not considered mission-critical | +| hotfix/\ | \ is a mission-critical bug, either affecting all users or a breaking change on a user's machines. These PRs should be reviewed ASAP | +| urgent/\ | Accepted as an alias for the above, due to dev's coming from multiple standards and the criticality of these issues | +| exp/\ | \ is a non-critical experiment. This is used for shipping around potential new features or fixes to multiple branches | +| merge/\ | \ is a temporary branch and should never be merged directly to main. This is solely used for addressing merge conflicts which are too complex to be merged directly on branch | + +## Secrets + +We allow secrets to be embedded in the repository using `sops-nix`. As part of +the process everything is encrypted, however adding a new user is a change +that every existing SOPS user needs to participate in. Please reach out to +@ahuston-0, @DerDennnisOP, or @RichieCahill if you are interested +in using secrets on your machines. + +## CI/CD + +Our CI is currently a detached Hydra instance, which does not provide +feedback to the repository. Research is being done into a GitHub bot which will +provide live feedback on PR's and such. + +Deployments are managed via two services for servers, one is the standard +`nixos-upgrade.service` which is bundled into NixOS. The current configuration +is that the `main` branch will be build every 24 hours on a per-server basis. +The other service is a custom `autopull@dotfiles.service`, which by default +will pull the `main` branch into `/root/dotfiles`. This service can be disabled +if you do not want it, but it is rather useful for experimenting and debugging.