From 056bac1617a39b26271ded0bc5e11800675b9bc6 Mon Sep 17 00:00:00 2001 From: javalsai Date: Sat, 2 May 2026 03:26:59 +0200 Subject: [PATCH] docs: extend README and add GETTING_STARTED.md - Talk about commit naming conventions - Specify the intent of the README - Separate less important stuff (getting started instructions) - Add development tooling to the getting started guide - Forbid AI _"vibecoding"_ while allowing moderate AI assistance --- docs/GETTING_STARTED.md | 36 +++++++++++++++++++++++++++++++++ docs/README.md | 44 ++++++++++++++++++++++------------------- 2 files changed, 60 insertions(+), 20 deletions(-) create mode 100644 docs/GETTING_STARTED.md diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md new file mode 100644 index 0000000..98f97a6 --- /dev/null +++ b/docs/GETTING_STARTED.md @@ -0,0 +1,36 @@ +Before interacting with anything in the repo, make sure you are familiar with all conventions documented in the [README](./README.md). + +# Nix Development Shells + +A Nix development shell is provided. To get a shell environment with basic tooling needed to work on this configuration, just run: + +```sh +nix develop +``` + +# NixOS System Configurations + +To test the environment, you can launch a virtualized NixOS system derived from the configuration: + +```sh +nix run '.#nixosConfigurations..config.system.build.vm' +``` + +Here, `` refers to the hostname of the system you want to test (e.g., tuxcord-ca). + +Note that this will create a `qcow2` image file in the current directory. Nix will automatically manage changes to the configuration and update the image file accordingly while keeping part of its mutable state (e.g., root bash history). + +> [!WARNING] +> Not all changes are applied automatically. Updates such as user passwords changes or modifications to the filesystem layout will require deleting the image file so that Nix can re-create it from scratch. + +# Tooling + +Tooling used to aid in development. + +## Formatter + +Formatting is done with the formatter defined in the Nix flake. This can be used with `nix fmt `. + +## Other + +- `codespell` can be used at the root of this project to scan for typos in all files. A `.codespellrc` is also provided to configure it properly. diff --git a/docs/README.md b/docs/README.md index ce4d405..87470bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,17 +4,33 @@ Declarative NixOS system configurations for [tuxcord](https://tuxcord.net/) serv Nix knowledge will be assumed arbitrarily; you should have basic understanding before diving into any details of this configuration. +You are required to read the entirety of this file before interacting further with this repository. + # Documentation -This README serves as the documentation entry point of this repository. Any other subcategories (e.g., users, structure, filesystem, security, services) should be documented using Markdown under this same directory. +This README serves as the documentation entry point of this repository. Any other subcategories (e.g., users, structure, filesystem, security, services) should be documented using Markdown under this same directory. We try to expose important naming and working conventions for anyone starting with this repository. Do keep in mind that documentation requires effort. This file can be outdated, incomplete, or inaccurate. Nothing will always be as accurate as the configuration itself. -# Repository +# Version Control Conventions + +Important considerations when working with the version history/repository of this repository. + +## Commit Naming + +This repository uses the **scoped commits** convention to describe commits. + +This means that every commit title must start with the part of the tree it affets (e.g. `nixos: [...]`, `nixos/programs: [...]`) or `treewide` for changes that affect the entirety of the repository. The rest of the title must be short, imperative, concise, and not contain any other scopes. Try to make it as simple as possible. + +There are no requirements for commit descriptions, though I suggest making them helpful (unless if the changes are already descriptive enough). No footers are required either (e.g., `Fixes #XXX`, `Signed-off-by`, `Assisted-by`). + +## Branches Active work is done in the `staging` branch, which will be periodically merged into the `main` branch. `main` is guaranteed to not break commit history unless absolutely required, whereas `staging` is relaxed in this regard and commit history may be rewritten if deemed appropriate. -# Hosts +# Infrastructure + +## Hosts There's currently a single shared tuxcord server, but we've already adopted a host naming convention in case this ever scales. @@ -24,29 +40,17 @@ Host specific configuration can be found at `nixos/hosts/tuxcord-XX`. This is us # Development -A Nix development shell is provided. To get a shell environment with basic tooling needed to work on this configuration, just run: +To learn how to get started, refer to the [Getting Started guide](./GETTING_STARTED.md). -``` sh -nix develop -``` - -To test the environment, you can launch a virtualized NixOS system derived from the configuration: - -```sh -nix run '.#nixosConfigurations..config.system.build.vm' -``` - -Here, `` refers to the hostname of the system you want to test (e.g., tuxcord-ca). - -Note that this will create a `qcow2` image file in the current directory. Nix will automatically manage changes to the configuration and update the image file accordingly while keeping part of its mutable state (e.g., root bash history). - -> [!WARNING] -> Not all changes are applied automatically. Updates such as user passwords changes or modifications to the filesystem layout will require deleting the image file so that Nix can re-create it from scratch. +The guide contains basic instructions as to how to use Nix for this repository, as well as tools to help in certain tasks. # Contributions For any contribution you would like to make, whether it is a discussion, a change, or another issue, there is no official channel, and the git server does not allow arbitrary user registration. We recommend contacting us via email (`javalsai@proton.me`/`javalsai@tuxcord.net`, `error@tuxcord.net`, or both). +> [!WARNING] +> No AI-generated code is allowed, especially _"vibecoding"_. AI assistance is allowed but it must always end with good quality human-written code. + # License All contents in this repository are licensed *exclusively* under the GNU Lesser General Public License (`LGPL-3.0-only`).