From 2549dc983766d9a9f3e92a27587bc489f96a3fe8 Mon Sep 17 00:00:00 2001 From: Achilleas Anagnostopoulos Date: Tue, 8 Aug 2017 22:56:58 +0100 Subject: [PATCH] Add contributing and status markdown files --- CONTRIBUTING.md | 52 ++++++++++++++++++++++++++++++++++++++++++++ STATUS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 STATUS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..45a1ff5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing Guide + +## Getting Started + +- Make sure you have a [GitHub Account](https://github.com/signup/free). +- Make sure you have [Git](http://git-scm.com/) installed on your system. +- [Fork](https://help.github.com/articles/fork-a-repo) the [repository](https://github.com/achilleasa/gopher-os) on GitHub. + +## Making Changes + + - [Create a branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository) for your changes. + - [Commit your code](http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository) for each logical change (see [tips for creating better commit messages](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message)). + - [Push your change](https://help.github.com/articles/pushing-to-a-remote) to your fork. + - [Create a Pull Request](https://help.github.com/articles/creating-a-pull-request) on GitHub for your change. + +The PR description should be as detailed as possible. This makes reviewing +much easier while at the same time serves as additional documentation that can +be referenced by future commits/PRs. + +This project treats the root folder of the repository as a Go [workspace](https://golang.org/doc/code.html#Workspaces). This +approach has several benefits: +- it keeps import paths short (no github.com/... prefix) +- it makes forking and merging easier +- it simplifies debugging (more compact symbol names) + +To develop for gopher-os you need to tweak your GOPATH so that the repository +folder is listed before any other GOPATH entry. This allows tools like +`goimports` to figure out the correct (short) import path for any gopher-os +package that your code imports. A simple way to do this would be by running the +following command: ```export GOPATH=`pwd`:$GOPATH```. + +## Unit tests and code linting + +Before submitting a PR make sure: +- that your code passes all lint checks: `make lint` +- you provide the appropriate unit-tests to ensure that the coverage does not + drop below the existing value (currently 100%). Otherwise, when you submit the + PR, the CI builder ([circle-ci](https://circleci.com)) will flag the build as + broken. + +Reaching 100% coverage is quite hard and requires the code to be designed with +testability in mind. This can get quite tricky if the code you are testing +relies on code that cannot be executed while running the tests. For example, if +the code you are currently working on needs to map some pages to virtual memory +then any call to the vmm package from your test code will cause the `go test` +to segfault. + +In cases like this, you need to design the code so calls to such packages can +be easily mocked while testing. If you are looking for inspiration here are +some examples that follow this approach: +- [bitmap allocator tests](https://github.com/achilleasa/gopher-os/blob/d804b17ed8651705f098d01bda65d8f0ded2c88e/src/gopheros/kernel/mem/pmm/allocator/bitmap_allocator_test.go#L15) +- [text console driver tests](https://github.com/achilleasa/gopher-os/blob/4b25971cef4bfd01877e3b5e948ee07a8f219608/src/gopheros/device/video/console/vga_text_test.go#L276) diff --git a/STATUS.md b/STATUS.md new file mode 100644 index 0000000..bbc58e2 --- /dev/null +++ b/STATUS.md @@ -0,0 +1,58 @@ +## Current project status + +Here is the list of features currently working as well as some of the next +steps in the project roadmap. + +#### Core kernel features +- Bootloader-related + - [x] Multboot structure parsing (boot cmdline, memory maps, framebuffer and kernel image details) +- CPU + - [x] CPUID wrapper + - [x] Port R/W abstraction +- Memory management + - [x] Physical frame allocators (bootmem-based, bitmap allocator) + - [x] VMM system (page table management, virtual address space reservations, page RW/NX bits, page walk/translation helpers and copy-on-write pages) +- Exception handling + - [x] Page fault handling (also used to implement CoW) + - [x] GPF handling +- Hardware detection/abstraction layer + - [x] Multiboot-based HW detection + - [ ] ACPI-based HW detection + +#### Supported Go language features: +- [x] Go allocator +- [x] Maps +- [x] Interfaces +- [x] Package init() functions +- [x] Defer +- [x] Panic +- [ ] GC +- [ ] Go-routines + +#### Device drivers +- Console + - [x] Text-mode console + - [x] Vesa-fb (15, 16, 24 and 32 bpp) console with support for bitmap fonts and (optional) logo +- TTY + - [x] Simple VT +- ACPI 6.2 support (**in progress**) + - [ ] ACPI table detection and parsing + - [ ] AML parser/interpreter +- Interrupt handling chip drivers + - [ ] APIC +- Timer and time-keeping drivers + - [ ] APM timer + - [ ] APIC timer + - [ ] HPET + - [ ] RTC +- Timekeeping system + - [ ] Monotonic clock (configurable timer implementation) +### Feature roadmap + +Here is a list of features planned for the future: +- RAMDISK support (tar/bz2) +- Loadable modules (using a mechanism analogous to Go plugins) +- Tasks and scheduling +- Network device drivers +- Hypervisor support +- POSIX-compliant VFS