mirror of
https://github.com/Plexi09/Nadir-Kernel.git
synced 2026-10-20 15:07:27 +02:00
Updated documentation
This commit is contained in:
parent
b010c43dab
commit
591c57c8f8
5 changed files with 68 additions and 49 deletions
2
.github/pull_request_template.md
vendored
2
.github/pull_request_template.md
vendored
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)).
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
38
docs/CONTRIBUTING.md
Normal file
38
docs/CONTRIBUTING.md
Normal file
|
|
@ -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).
|
||||
28
docs/SECURITY.md
Normal file
28
docs/SECURITY.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue