From 591c57c8f8231be82d4dfc4538e2286495f8afce Mon Sep 17 00:00:00 2001 From: "Pierre-Emmanuel Gob." Date: Sat, 19 Sep 2026 22:44:59 +0200 Subject: [PATCH] Updated documentation --- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 47 -------------------------------- README.md | 2 +- docs/CONTRIBUTING.md | 38 ++++++++++++++++++++++++++ docs/SECURITY.md | 28 +++++++++++++++++++ 5 files changed, 68 insertions(+), 49 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/SECURITY.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 99106d5..6ed8328 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,4 +8,4 @@ - [ ] Boots in QEMU and shows the expected output - [ ] No generated artifacts committed (`*.o`, `*.bin`, `*.iso`, `build/` etc) - [ ] Documentation updated if behavior changed -- [ ] AI policy respected: code is human-authored (or fully understood) see [CONTRIBUTING.md](CONTRIBUTING.md) +- [ ] Code is human-authored (or fully understood) see [CONTRIBUTING.md](../docs/CONTRIBUTING.md) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f8451b8..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,47 +0,0 @@ -# Contributing to Nadir - -Thanks for considering contributing to Nadir. This project is deliberately small and human-driven. Every line of code must be understood by its author. Please read this guide and the [README](README.md) before opening a pull request. - -## AI use policy - -AI assistance is allowed, but it must stay **minimal**. Nadir is a craft project. The majority of the code must be written by a human. - -Please stick to the following rules if you plan to use AI in your contributions: -- The majority of the code must be authored by a human. Use AI as a tutor, reviewer, or rubber duck if you need help. Do not as a bulk code generator. -- Never paste large AI-generated chunks into the tree. Small and reviewable changes only. -- **You are responsible for every committed line.** If you cannot explain an AI-suggested snippet, rewrite it until you can. Do not commit code you do not understand. -- **Everything must be documented.** Committed code, human or AI-authored, must be well documented. Undocumented code WILL be regected. -- **Attribution is not welcome, it's required.** If a commit contains meaningful AI-assisted work, add a `Co-Authored-By:` trailer or mention it in the PR description. - -## Ground rules - -- Bare-metal only: `-ffreestanding -fno-builtin`, no libc, no host headers, no syscalls, no `printf()`/`malloc()` from the host. -- Never commit generated artifacts: `*.o`, `*.a`, `*.elf`, `*.bin`, `*.iso`, `*.img`, `build/` (see `.gitignore`). -- One subsystem per file. Architecture-specific code never leaks into `kernel/core/`. -- Keep the kernel bootable. Every change must still build and boot in QEMU. - -## Code style - -- C11 or C17, plus NASM/GAS assembly. No K&R-style code. -- Compile-clean discipline: `-Wall -Wextra -Werror`. -- Match the surrounding style. - -## Documentation - -- Every function, type, and file gets a doc comment explaining its purpose and, when relevant, the *why*, not just the obvious *what*. -- Every privileged primitive (GDT, IDT, paging, context switch) must document the Ring / CPL it operates in and its fault behavior. - -## Building and running - -Build from the repository root. See the [README](README.md) for prerequisites and troubleshooting: - -``` -make # builds nadir.img (boot sector + kernel) -make run # boots it in QEMU -``` - -The toolchain is not yet finalized (candidates: `gcc` cross + `ld`, or `clang` + `lld` + `nasm`; target `x86-64-elf`). - -## License - -By contributing, you agree that your contributions are licensed under the project's license (MIT — see [LICENSE](LICENSE)). \ No newline at end of file diff --git a/README.md b/README.md index d0bb3a2..06b2d76 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ The full memory map lives in the header comment of `kernel/arch/x86_64/boot.asm` ## Contributing -Every contribution is welcome. Please fork and send a pull request if you wish to contribute. You will be credited at the end of this very file. Please see [CONTRIBUTING](CONTRIBUTING.md) for more information. +Every contribution is welcome. Please fork and send a pull request if you wish to contribute. You will be credited at the end of this very file. Please see [CONTRIBUTING](docs/CONTRIBUTING.md) for more information. ## AI Usage diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..e79f5bc --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,38 @@ +# Contributing to Nadir + +Thanks for considering contributing to Nadir. This project is deliberately small and human-driven. Every line of code must be understood by its author. Please read this guide and the [README](../README.md) before opening a pull request. + +## AI use policy + +AI assistance is allowed, but it must stay **minimal** + +Please stick to the following rules if you plan to use AI in your contributions: +- The majority of the code must be authored by a human. Use AI as a tutor or reviewer if you need help. +- Never paste large AI-generated chunks into the tree. +- You are responsible for every committed line. +- Everything must be documented. Committed code, human or AI-authored, must be well documented. Undocumented code WILL be regected. +- Attribution is not welcome, it's required. If a commit contains meaningful AI-assisted work, add a `Co-Authored-By:` trailer in the PR description. + +## Ground rules + +- Never commit generated artifacts: `*.o`, `*.a`, `*.elf`, `*.bin`, `*.iso`, `*.img`, `build/` (see `.gitignore`). +- Every change must still build and boot in QEMU. + +## Code style + +- C11 or C17, plus NASM/GAS assembly. +- Compile-clean discipline: `-Wall -Wextra -Werror`. +- Match the surrounding style. + +## Documentation + +- Every function, type, and file gets a doc comment explaining its purpose and, when relevant, the *why*. +- Every privileged primitive (GDT, IDT, paging, context switch) must document the Ring / CPL it operates in and its fault behavior. + +## Building and running + +Build from the repository root. See the [README](../README.md). + +## License + +By contributing, you agree that your contributions are licensed under the project's license. See [LICENSE](../LICENSE). \ No newline at end of file diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 0000000..f5eca09 --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,28 @@ +# Security Policy + +## Supported versions + +Nadir is a hobby x86-64 kernel. Only the tip of `main` is supported. + +| Version | Supported | +| ------- | ------------------ | +| `main` | :white_check_mark: | +| Anything else | :x: | + +If you report an issue against an old commit, please verify it still reproduces on current `main` first (`make` then `make run` in QEMU). + +## Reporting a vulnerability + +Use a [private security advisory](https://github.com/Plexi09/Nadir-Kernel/security/advisories/new) +This keeps the details private until a fix is ready. + +Please include: + +1. What you think is wrong and why it matters +2. Steps to reproduce and serial/VGA output or a `-d int -no-reboot` log. + +## Out of scope + +- QEMU, SeaBIOS, firmware, host toolchain and host OS +- Denial of service by crashing +- Missing hardening as such