diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..567f0f7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# 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 + +The current toolchain is two commands from the repository root. See the [README](README.md) for prerequisites and troubleshooting: + +``` +nasm -f bin boot.asm -o boot.bin +qemu-system-x86_64 -fda boot.bin +``` + +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 d6b3063..f48f2e7 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,9 @@ Notes: | Black screen / blinking cursor | The boot sector only speaks legacy BIOS (`int 0x10` text mode). This works out of the box with QEMU's default SeaBIOS firmware but will not boot under UEFI-only firmware (or UEFI-only real hardware) unless legacy/CSM boot is enabled. | | No window appears under WSL2 | Use the `-display curses` variant above. It should work in any terminal. | +## 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 the [CONTRIBUTING](CONTRIBUTING.md) file for more information. ## License