From af3b1d5c558487a1b5acccc7031470241cc153f8 Mon Sep 17 00:00:00 2001
From: aileot <46470475+aileot@users.noreply.github.com>
Date: Sun, 16 Feb 2025 08:49:10 +0900
Subject: [PATCH 1/2] docs(contributing): add CONTRIBUTING.md

---
 CONTRIBUTING.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..70d55e2
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,103 @@
+# Contributing
+
+> [!IMPORTANT]
+> This project is mainly written in [Fennel][] to be transpiled to Lua.
+> The Lua files under `fnl/` are also copied to `lua/` directory.
+>
+> Do **NOT** directly edit **any** Lua files under `lua/` directory.
+> Instead, edit the files under `fnl/` directory.
+
+Any kind of contributions are welcome.
+
+Before any changes,
+please run [`make init`](#make-init)
+at the repository's root directory.
+For larger features,
+please open an issue first to avoid duplicate work.
+
+## Building
+
+### `make build`
+
+This command will do two things:
+
+1. Transpile all the updated **Fennel** files
+   under `fnl/` to `lua/` directory.
+2. Copy all the updated **Lua** files
+   under `fnl/` to `lua/` directory.
+
+This command is also executed automatically on [`make test`](#testing)
+and
+(once you run [`make init`](#make-init))
+on `git-commit`.
+
+See also the section:
+[How to resolve conflicts in `lua/`](#how-to-resolve-conflicts-in-lua).
+
+### `make init`
+
+This command will setup the project:
+
+1. Activate [`.githooks/`](./.githooks).\
+   This helps automatically keep the files under `lua/` up-to-date on every
+   `git-commit`.
+   Note that you cannot stage unrelated Lua files under `lua/`
+   if there are no corresponding files staged under `fnl/`.
+   It also helps you resolve conflicts in the generated files under `lua/`.
+   Follow the [section](#how-to-resolve-conflicts-in-lua) below
+   for the details.
+
+2. Generate `.envrc` for nix users.\
+   It only helps if you have `nix` and `direnv` installed.
+   Please check the `.envrc` contents, and run `direnv allow`.
+
+### How to resolve conflicts in `lua/`
+
+(Please make sure you have already run [`make init`](#make-init).)
+
+1. Resolve all conflicts in `fnl/` at the commit.
+2. Run `make clean build`.
+3. Done!
+   All the Lua files should be up-to-date without any conflicts.
+
+### Architecture
+
+As described above, this project is mainly written in [Fennel][];
+however, some files are written in Lua under `fnl/`:
+
+- `config.lua`
+  to make it easier for prospective contributors unfamiliar with [Fennel][].
+
+```tree
+fnl/
+└── emission/
+    └── config.lua
+```
+
+## Testing
+
+1. Make sure [Requirements](#test-requirements) are installed,
+   or follow the steps [for nix users](#testing-for-nix-users).
+2. Run `make test`.
+
+### Test Requirements
+
+- [make][]: the build/test interface
+- [fennel][]: the compiler
+- [vusted][]: the test runner
+
+#### Testing for nix users
+
+If you have `nix` installed,
+you can automate the requirement installation
+with the following options enabled:
+
+1. `flake` feature
+2. `programs.direnv.enable`
+
+Then, run `direnv allow` in this project directory.
+Otherwise, please run `nix develop` in this project directory.
+
+[fennel]: https://sr.ht/~technomancy/fennel/
+[make]: https://www.gnu.org/software/make/manual/html_node/index.html
+[vusted]: https://github.com/notomo/vusted

From 099d5b142042c3ff719748f4ac9a32dab30f1dc3 Mon Sep 17 00:00:00 2001
From: aileot <46470475+aileot@users.noreply.github.com>
Date: Sun, 16 Feb 2025 12:44:38 +0900
Subject: [PATCH 2/2] docs(contributing): describe `make init` first

---
 CONTRIBUTING.md | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 70d55e2..6a12d43 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,23 +17,6 @@ please open an issue first to avoid duplicate work.
 
 ## Building
 
-### `make build`
-
-This command will do two things:
-
-1. Transpile all the updated **Fennel** files
-   under `fnl/` to `lua/` directory.
-2. Copy all the updated **Lua** files
-   under `fnl/` to `lua/` directory.
-
-This command is also executed automatically on [`make test`](#testing)
-and
-(once you run [`make init`](#make-init))
-on `git-commit`.
-
-See also the section:
-[How to resolve conflicts in `lua/`](#how-to-resolve-conflicts-in-lua).
-
 ### `make init`
 
 This command will setup the project:
@@ -51,6 +34,23 @@ This command will setup the project:
    It only helps if you have `nix` and `direnv` installed.
    Please check the `.envrc` contents, and run `direnv allow`.
 
+### `make build`
+
+This command will do two things:
+
+1. Transpile all the updated **Fennel** files
+   under `fnl/` to `lua/` directory.
+2. Copy all the updated **Lua** files
+   under `fnl/` to `lua/` directory.
+
+This command is also executed automatically on [`make test`](#testing)
+and
+(once you run [`make init`](#make-init))
+on `git-commit`.
+
+See also the section:
+[How to resolve conflicts in `lua/`](#how-to-resolve-conflicts-in-lua).
+
 ### How to resolve conflicts in `lua/`
 
 (Please make sure you have already run [`make init`](#make-init).)