Skip to content

Commit 44fc58d

Browse files
pedrobrantespedrobrantes
committed
docs: Add initial project documentation guides
1 parent 7e66fe3 commit 44fc58d

3 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎DEVELOPMENT.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Development Guide
2+
3+
This document outlines the development workflow for managing and extending these dotfiles. The goal is to maintain a clean, stable, and testable configuration by using a `develop` branch for integration and keeping `main` as a stable release branch.
4+
5+
## Architectural Approach: Declarative Modular Monolith
6+
7+
This project is built on the **declarative nature** of Nix and organized as a **modular monolith**.
8+
9+
- **Declarative**: The core principle of Nix. We do not write scripts that command the system to *do* things (e.g., `apt install htop`). Instead, we write `.nix` files that **declare the desired final state** of the system (e.g., `packages = [ htop ];`). Nix's job is to figure out the steps to make the system match this declaration, ensuring reproducible and reliable environments.
10+
11+
- **Monolith**: The entire user environment is defined as a single, cohesive configuration that is deployed atomically with a single `home-manager switch` command. This ensures the whole system is always in a consistent state.
12+
13+
- **Modular**: Internally, this monolith is broken down into independent modules (e.g., `git.nix`, `zsh.nix`). Each module declaratively defines a specific tool or piece of functionality. This structure makes it easy to manage, update, and understand individual components without affecting the whole.
14+
15+
## Branching and Release Workflow
16+
17+
We use two primary branches to manage changes:
18+
- `develop`: The main development branch. All new features are integrated here. It should always be functional, but it's where active development happens.
19+
- `main`: The stable release branch. This branch only receives updates from `develop` when a set of features is complete and considered stable.
20+
21+
### Feature Development (Day-to-Day Cycle)
22+
23+
All new work, from adding a small tool to a big refactor, follows this cycle.
24+
25+
#### 1. Create a New Branch from `develop`
26+
27+
Before starting any work, create your feature branch from the latest version of the **`develop`** branch.
28+
29+
```bash
30+
# Get the latest version of the develop branch
31+
git checkout develop
32+
git pull origin develop
33+
34+
# Create your new feature branch
35+
git checkout -b feature/add-btop-config
36+
```
37+
38+
#### 2. Add New Configurations and Tests
39+
40+
Make your changes to the `.nix` files, preferably by creating a new, self-contained module.
41+
42+
**Crucially, for any new functionality, add a corresponding test** in the `nix_tests` directory. This ensures our CI pipeline can validate your changes automatically. (See the [TEST TEMPLATES](./nix_tests/TEST_TEMPLATES.md) for examples).
43+
44+
#### 3. Commit and Push
45+
46+
Commit your changes to your feature branch and push it to the remote repository. Use a descriptive commit message following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
47+
48+
```bash
49+
git add .
50+
git commit -m "feat: Add configuration for btop"
51+
git push -u origin feature/add-btop-config
52+
```
53+
54+
#### 4. Open a Pull Request to `develop`
55+
56+
Go to your repository on GitHub and open a Pull Request (PR) from your feature branch to the **`develop`** branch.
57+
58+
The CI pipeline will run on the PR. After it passes and you are satisfied with the changes, you can merge it into `develop`.
59+
60+
### Releasing to `main` (Promoting to Stable)
61+
62+
Periodically, when the `develop` branch contains a stable and complete set of features, you can create a new "release" on the `main` branch.
63+
64+
1. **Merge `develop` into `main`**:
65+
```bash
66+
# Go to the main branch and make sure it's up to date
67+
git checkout main
68+
git pull origin main
69+
70+
# Merge all the changes from develop into main
71+
git merge develop --no-ff -m "chore(release): Merge develop into main"
72+
73+
# Push the updated main branch
74+
git push origin main
75+
```
76+
*(`--no-ff` creates a merge commit, which is good for visualizing the history of releases).*
77+
78+
2. **(Optional) Create a Version Tag**:
79+
After merging to `main`, it is good practice to create a tag to mark the new version.
80+
```bash
81+
git tag -a v1.1.0 -m "Release v1.1.0"
82+
git push origin v1.1.0
83+
```

‎README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# My Dotfiles
2+
3+
This repository contains my personal Nix configurations. It's managed by Nix and is designed to be reproducible across different machines.
4+
5+
The configuration is built with a **modular monolithic** approach. While the entire configuration is managed as a single unit (monolith), it is internally organized into logical, independent modules (e.g., for git, zsh, neovim). This structure makes it easy to manage, update, and understand individual components without affecting the whole system.
6+
7+
For details on how to add new configurations and run tests, please see the [**Development Guide (DEVELOPMENT.md)**](./DEVELOPMENT.md).
8+
9+
## Setup on a New Machine
10+
11+
Setting up a new machine from scratch involves these steps:
12+
13+
### 1. Install Nix
14+
15+
First, install the Nix package manager. The recommended multi-user installation is preferred. Open a terminal and run:
16+
17+
```bash
18+
sh <(curl -L [https://nixos.org/nix/install](https://nixos.org/nix/install)) --daemon
19+
```
20+
Follow the on-screen instructions. After the installation, close and reopen your terminal to ensure the Nix environment is loaded.
21+
22+
### 2. Install Home Manager
23+
24+
With Nix installed, install Home Manager using the specific **25.05** release channel.
25+
26+
```bash
27+
nix-channel --add [https://github.com/nix-community/home-manager/archive/release-25.05.tar.gz](https://github.com/nix-community/home-manager/archive/release-25.05.tar.gz) home-manager
28+
nix-channel --update
29+
nix-shell '<home-manager>' -A install
30+
```
31+
This will create the initial Home Manager files and directories.
32+
33+
### 3. Clone This Repository
34+
35+
Clone this repository into the Home Manager configuration directory (`~/.config/home-manager`).
36+
37+
```bash
38+
git clone git@github.com:pedrobrantes/dotfiles.git ~/.config/home-manager
39+
```
40+
41+
### 4. Apply the Configuration
42+
43+
Navigate to the directory and run `home-manager switch`. This command builds your configuration and activates it, creating all the necessary symlinks.
44+
45+
```bash
46+
cd ~/.config/home-manager
47+
home-manager switch
48+
```
49+
Your environment is now fully configured!

‎nix_tests/TEST_TEMPLATES.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
### Base Template
2+
3+
This is the clean structure to be used for all test files.
4+
5+
```bash
6+
#!/usr/bin/env bash
7+
set -euo pipefail
8+
9+
echo "--> Testing: <program_name> <test_name>"
10+
# <test_logic>
11+
echo "OK: <program_name> <test_function> is correct."
12+
```
13+
14+
-----
15+
16+
### Practical Examples
17+
18+
Here is how you implement the `<test_logic>` for common scenarios.
19+
20+
#### 1\. To Check if a Command Exists
21+
22+
This test verifies that the `nvim` executable is available in the `$PATH`.
23+
24+
**`nix_tests/tools/test_nvim_exists.sh`**
25+
26+
```bash
27+
#!/usr/bin/env bash
28+
set -euo pipefail
29+
30+
echo "--> Testing: Neovim Installation"
31+
if ! command -v nvim &> /dev/null; then
32+
echo "FAIL: nvim command not found." >&2
33+
exit 1
34+
fi
35+
echo "OK: nvim command is available in PATH."
36+
```
37+
38+
#### 2\. To Check an Environment Variable's Value
39+
40+
This test verifies that the `$EDITOR` environment variable is set to `nvim`.
41+
42+
**`nix_tests/env/test_editor_variable.sh`**
43+
44+
```bash
45+
#!/usr/bin/env bash
46+
set -euo pipefail
47+
48+
echo "--> Testing: Editor Environment Variable"
49+
expected="nvim"
50+
actual="${EDITOR:-not_set}"
51+
if [[ "$actual" != "$expected" ]]; then
52+
echo "FAIL: EDITOR is '$actual', expected '$expected'." >&2
53+
exit 1
54+
fi
55+
echo "OK: EDITOR is set to nvim."
56+
```
57+
58+
#### 3\. To Check if a Configuration File Exists
59+
60+
This test verifies that the git configuration file has been created at the expected path.
61+
62+
**`nix_tests/git/test_config_exists.sh`**
63+
64+
```bash
65+
#!/usr/bin/env bash
66+
set -euo pipefail
67+
68+
echo "--> Testing: Git Config File Existence"
69+
config_file="$HOME/.config/git/config"
70+
if [[ ! -f "$config_file" ]]; then
71+
echo "FAIL: Git config file not found at $config_file." >&2
72+
exit 1
73+
fi
74+
echo "OK: Git config file exists."
75+
```
76+
77+
#### 4\. To Check a File's Content
78+
79+
This test verifies that your name is correctly set inside the git config file.
80+
81+
**`nix_tests/git/test_user_name.sh`**
82+
83+
```bash
84+
#!/usr/bin/env bash
85+
set -euo pipefail
86+
87+
echo "--> Testing: Git User Name"
88+
config_file="$HOME/.config/git/config"
89+
expected_line="name = Pedro Brantes"
90+
if ! grep -q "$expected_line" "$config_file"; then
91+
echo "FAIL: User name not found or incorrect in $config_file." >&2
92+
exit 1
93+
fi
94+
echo "OK: Git user name is correct."
95+
```

0 commit comments

Comments
 (0)