docs/README: update language

- Use more active and direct phrasing

- Remove unnecessary qualifiers

- Add some punctuation

- Clarify legal phrasing
This commit is contained in:
2026-05-01 21:07:35 -04:00
parent 9f01957406
commit d57eb12760
+15 -15
View File
@@ -2,53 +2,53 @@
Declarative NixOS system configurations for [tuxcord](https://tuxcord.net/) server infrastructure. Declarative NixOS system configurations for [tuxcord](https://tuxcord.net/) server infrastructure.
You should have basic nix knowledge before diving into any details of this configuration as nix knowledge will be assumed arbitrarily. Nix knowledge will be assumed arbitrarily; you should have basic understanding before diving into any details of this configuration.
# Documentation # Documentation
This README serves as the documentation entry point of the repository, any other specific aspects like users, structure, filesystem, security, services, etc, should be documented in markdown under this same `docs/` 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.
Mind that documentation takes work and this can be outdated or not completely accurate, remember that nothing will always be as accurate as the configuration code itself. 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 # Repository
Active work is done in the `staging` branch, which get periodically merged into `main` branch. `main` is guaranteed to not break commit history unless explicitly required, `staging` is relaxed in this regard and can rewrite commit history if we deem it appropriate. 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 # Hosts
There's currently a single tuxcord shared server, but we've already adopted a host naming convention in case this ever scales. There's currently a single shared tuxcord server, but we've already adopted a host naming convention in case this ever scales.
That is, hostnames are `tuxcord-<region>`, where `<region>` is the lowercase two-letter national code of the geographical location. We doubt there will ever be more than a server per country, so further disambiguation is not specified. Hostnames follow the format `tuxcord-<region>`, where `<region>` is the lowercase two-letter country code representing the server's geographical location. We doubt there will ever be more than one server per country, so further disambiguation is not defined.
Host specific configuration can be found at `nixos/hosts/tuxcord-XX`, this is useful for host specific hardware, firmware, storage layout, etc. Host specific configuration can be found at `nixos/hosts/tuxcord-XX`. This is useful for host-specific hardware, firmware, storage layouts, etc.
# Development # Development
To get an environment with the basic tooling there's a nix development shell provided, just run: A Nix development shell is provided. To get a shell environment with basic tooling needed to work on this configuration, just run:
``` sh ``` sh
nix develop nix develop
``` ```
To test the environment you can use nix utilities to virtualize a NixOS system configuration: To test the environment, you can launch a virtualized NixOS system derived from the configuration:
```sh ```sh
nix run '.#nixosConfigurations.<system>.config.system.build.vm' nix run '.#nixosConfigurations.<system>.config.system.build.vm'
``` ```
Where `<system>` is the name of a host to test, for example `tuxcord-ca`. Here, `<system>` refers to the hostname of the system you want to test (e.g., tuxcord-ca).
Mind that this will create a `qcow2` image file in the project 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). 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] > [!WARNING]
> Not all changes will be updated properly, mind that changes to user passwords or changes in the filesystem layout will require the image file to be deleted so that nix can recreate it from scratch. > 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.
# Contributions # Contributions
For any contribution you'd like to make, whether it's a discussion, changes, or any other issue, there's no official channel nor does this git server allow arbitrary user registration. But we recommend reaching out to us through email (`javalsai@proton.me`/`javalsai@tuxcord.net`, `error@tuxcord.net`, or both). 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).
# License # License
All contents under this repository are licensed under the GNU Lesser General Public License **only** (`LGPL-3.0-only`). All contents in this repository are licensed *exclusively* under the GNU Lesser General Public License (`LGPL-3.0-only`).
You are free to use work based on this configuration for your own systems and redistribute modifications as long as you uphold the license terms. You are permitted to use derivatives of this configuration for your own systems and to redistribute modified versions, provided that you comply with the terms of the license.