Add contributing and readme
This commit is contained in:
Jeremy Soller
parent
25743a89a2
commit
d38ec4e09b
163
CONTRIBUTING.md
Normal file
163
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
# Contributing to Redox
|
||||
|
||||
Thank you for your interest in contributing to Redox! This document is a guide to help newcomers contribute!
|
||||
There are many ways to help us out and we appreciate all of them.
|
||||
|
||||
## Index
|
||||
|
||||
* [Communication](#communication)
|
||||
* [Chat](#chat)
|
||||
* [Reddit](#reddit)
|
||||
* [Direct Contributing](#direct-contributing)
|
||||
* [Low-Hanging Fruit - Easy Targets for Newbies](#easy-targets)
|
||||
* [GitHub Issues](#gh-issues)
|
||||
* [Pull Requests](#prs)
|
||||
* [Creating a Pull Request](#creating-a-pr)
|
||||
* [Best Practices/Guidelines](#best-practices)
|
||||
* [General](#general)
|
||||
* [Kernel](#kernel)
|
||||
* [Testing Practices](#testing-practices)
|
||||
* [Style Guidelines](#style-guidelines)
|
||||
* [Rust](#rust-style-guidelines)
|
||||
* [Git](#git-style-guidelines)
|
||||
* [Other Ways to Contribute](#other)
|
||||
* [Graphic Design](#graphic-design)
|
||||
|
||||
## <a name="extern-links"> Other External Links </a>
|
||||
|
||||
* [redox-os.org](http://redox-os.org)
|
||||
* [rust-os-comparison](https://github.com/flosse/rust-os-comparison)
|
||||
* [rust-lang.org](http://rust-lang.org)
|
||||
|
||||
## <a name="communication"> Communication </a>
|
||||
|
||||
### <a name="chat"> Chat </a>
|
||||
|
||||
The quickest and most open way to communicate with the Redox team is on our chat server. Currently, the only way to join it is by sending an email to [info@redox-os.org](mailto:info@redox-os.org), which might take a little while, since it's not automated. We're currently working on an easier way to do this, but this is the most convenient way right now.
|
||||
|
||||
### <a name="reddit"> Reddit </a>
|
||||
|
||||
You can find Redox on Reddit in [/r/rust/](https://www.reddit.com/r/rust) and [/r/redox/](https://www.reddit.com/r/redox). The weekly update news is posted on the former.
|
||||
|
||||
## <a name="direct-contributing"> Direct Contributing </a>
|
||||
|
||||
### <a name="easy-targets"> Low-Hanging Fruit - Easy Targets for Newbies </a>
|
||||
|
||||
* If you're not fluent in Rust:
|
||||
|
||||
* Writing documentation
|
||||
* Using/testing Redox, filing issues for bugs and needed features
|
||||
* Web development ([Redox website, separate repo](https://github.com/redox-os/website))
|
||||
* Writing unit tests (may require minimal knowledge of rust)
|
||||
|
||||
* If you are fluent in Rust, but not OS Development:
|
||||
|
||||
* Apps development
|
||||
* Shell ([Ion](https://github.com/redox-os/ion)) development
|
||||
* Package manager ([Magnet](https://github.com/redox-os/magnet)) development
|
||||
* Other high-level code tasks
|
||||
|
||||
* If you are fluent in Rust, and have experience with OS Dev:
|
||||
|
||||
* Familiarize yourself with the repository and codebase
|
||||
* Grep for `TODO`, `FIXME`, `BUG`, `UNOPTIMIZED`, `REWRITEME`, `DOCME`, and `PRETTYFYME` and fix the code you find.
|
||||
* Improve and optimize code, especially in the kernel
|
||||
|
||||
### <a name="gh-issues"> GitHub Issues </a>
|
||||
|
||||
A bit more formal way of communication with fellow Redox devs, but a little less quick and convenient like the chat (unless of course you aren't in it yet, which if you're going to be involved in this project really at all, it is recommended that you request to join). These are for more specific topics.
|
||||
|
||||
### <a name="prs"> Pull Requests </a>
|
||||
|
||||
It's completely okay to just submit a small pull request without first making an issue or something, but if it's a significant change that will require a lot of planning and reviewing, it's best you start with writing an issue first. Also see [git guidelines](#git-style-guidelines)
|
||||
|
||||
### <a name="creating-a-pr"> Creating a Pull Request </a>
|
||||
|
||||
1. Fork the repository
|
||||
2. Clone the original repository to your local PC using one of the following commands based on the protocol you are using:
|
||||
* HTTPS:`git clone https://github.com/redox-os/redox.git --origin upstream --recursive`
|
||||
* SSH:`git clone git@github.com:redox-os/redox.git --origin upstream --recursive`
|
||||
* Then rebase: `git rebase upstream master`
|
||||
Use HTTPS if you don't know which one to use. (Recommended: learn about SSH if you don't want to have to log in every time you push/pull!)
|
||||
3. Add your fork with
|
||||
* HTTPS:`git remote add origin https://github.com/your-username/redox.git`
|
||||
* SSH:`git remote add origin git@github.com:your-username/redox.git`
|
||||
4. Alternatively, if you already have a fork and copy of the repo, you can simply check to make sure you're up-to-date
|
||||
* Fetch the upstream:`git fetch upstream master`
|
||||
* Rebase with local commits:`git rebase upstream/master`
|
||||
* Update the submodules:`git submodule update --init`
|
||||
5. Optionally create a separate branch (recommended if you're making multiple changes simultaneously) (`git checkout -b my-branch`)
|
||||
6. Make changes
|
||||
7. Commit (`git add . --all; git commit -m "my commit"`)
|
||||
8. Optionally run [rustfmt](https://github.com/rust-lang-nursery/rustfmt) on the files you changed and commit again if it did anything (check with `git diff` first)
|
||||
9. Test your changes with `make qemu` or `make virtualbox` (you might have to use `make qemu kvm=no`, formerly `make qemu_no_kvm`)
|
||||
(see [Best Practices and Guidelines](#best-practices))
|
||||
10. Pull from upstream (`git fetch upstream; git rebase upstream/master`) (Note: try not to use `git pull`, it is equivalent to doing `git fetch upstream; git merge master upstream/master`, which is not usually preferred for local/fork repositories, although it is fine in some cases.)
|
||||
11. Repeat step 9 to make sure the rebase still builds and starts
|
||||
12. Push to your fork (`git push origin my-branch`)
|
||||
13. Create a pull request
|
||||
14. Describe your changes
|
||||
15. Submit!
|
||||
|
||||
## <a name="best-practices"> Best Practices and Guidelines </a>
|
||||
|
||||
### <a name="general"> General </a>
|
||||
|
||||
* **Remember to do a `git rebase -i upstream/master` before you send your patch!**
|
||||
* **Make sure your code is readable, commented, and well-documented.**
|
||||
* **Don't hesitate to ask for help!**
|
||||
* **Before implementing something, discuss it! Open an issue, or join the chat.**
|
||||
|
||||
##### On the more technical side:
|
||||
* Test, test, and test!
|
||||
* Follow the style conventions
|
||||
* Use `std::mem::replace` and `std::mem::swap` when you can.
|
||||
* `libredox` should be 1-to-1 with the official `libstd`.
|
||||
* Use `.into()` and `.to_owned()` over `.to_string()`.
|
||||
* Prefer passing references to the data over owned data. (Don't take `String`, take `&str`. Don't take `Vec<T>` take `&[T]`).
|
||||
* Use generics, traits, and other abstractions Rust provides.
|
||||
* Avoid using lossy conversions (for example: don't do `my_u32 as u16 == my_u16`, prefer `my_u32 == my_u16 as my_u32`).
|
||||
* Prefer in place (`box` keyword) when doing heap allocations.
|
||||
* Prefer platform independently sized integer over pointer sized integer (`u32` over `usize`, for example).
|
||||
* Follow the usual idioms of programming, such as "composition over inheritance", "let your program be divided in smaller pieces", and "resource acquisition is initialization".
|
||||
* When `unsafe` is unnecessary, don't use it. 10 lines longer safe code is better than more compact unsafe code!
|
||||
* Be sure to mark parts that need work with `TODO`, `FIXME`, `BUG`, `UNOPTIMIZED`, `REWRITEME`, `DOCME`, and `PRETTYFYME`.
|
||||
* Use the compiler hint attributes, such as `#[inline]`, `#[cold]`, etc. when it makes sense to do so.
|
||||
* Check the [chat](#chat), [the Website](http://redox-os.org), and [the Rust subreddit](https://www.reddit.com/r/rust) frequently.
|
||||
|
||||
### <a name="kernel"> Kernel </a>
|
||||
|
||||
* When trying to access a slice, **always** use the `common::GetSlice` trait and the `.get_slice()` method to get a slice without causing the kernel to panic.
|
||||
The problem with slicing in regular Rust, e.g. `foo[a..b]`, is that if someone tries to access with a range that is out of bounds of an array/string/slice, it will cause a panic at runtime, as a safety measure. Same thing when accessing an element.
|
||||
Always use `foo.get(n)` instead of `foo[n]` and try to cover for the possibility of `Option::None`. Doing the regular way may work fine for applications, but never in the kernel. No possible panics should ever exist in kernel space, because then the whole OS would just stop working.
|
||||
|
||||
### <a name="testing-practices"> Testing Practices </a>
|
||||
|
||||
* It's always better to test boot (`make qemu` or `make virtualbox`) every time you make a change, because it is important to see how the OS boots and works after it compiles.
|
||||
Even though Rust is a safety-oriented language, something as unstable as an in-dev operating system will have problems in many cases and may completely break on even the slightest critical change.
|
||||
Also, make sure you check how the unmodified version runs on your machine before making any changes. Else, you won't have anything to compare to, and it will generally just lead to confusion. TLDR: Rebuild and test boot often.
|
||||
|
||||
* To run the ZFS tests:
|
||||
* Create the zfs.img only once. If one has not been created, run `make filesystem/apps/zfs/zfs.img` before booting into Redox.
|
||||
* Run `open zfs.img` to open the created ZFS image.
|
||||
* Run `file /home/LICENSE.md` twice to ensure ARC isn't broken.
|
||||
|
||||
## <a name="style-guidelines"> Style Guidelines </a>
|
||||
|
||||
### <a name="rust-style-guidelines"> Rust </a>
|
||||
|
||||
Since Rust is a relatively small and new language compared to others like C, there's really only one standard. Just follow the official Rust standards for formatting, and maybe run `rustfmt` on your changes, until we setup the CI system to do it automatically.
|
||||
|
||||
### <a name="git-style-guidelines"> Git </a>
|
||||
|
||||
* Commit messages should describe their changes in present tense, e.g. "`Add stuff to file.ext`" instead of "`added stuff to file.ext`".
|
||||
* Try to remove useless duplicate/merge commits from PRs as these clutter up history, and may make it hard to read.
|
||||
* Usually, when syncing your local copy with the master branch, you will want to rebase instead of merge. This is because it will create duplicate commits that don't actually do anything when merged into the master branch.
|
||||
* When you start to make changes, you will want to create a separate branch, and keep the `master` branch of your fork identical to the main repository, so that you can compare your changes with the main branch and test out a more stable build if you need to.
|
||||
* You should have a fork of the repository on GitHub and a local copy on your computer. The local copy should have two remotes; `upstream` and `origin`, `upstream` should be set to the main repository and `origin` should be your fork.
|
||||
|
||||
## <a name="other"> Other Ways to Contribute </a>
|
||||
|
||||
### <a name="graphic-design"> Graphic Design </a>
|
||||
|
||||
If you're a good designer, you can help with logos, UI design, app icons, other graphics (e.g. stock desktop backgrounds), etc. More information to come on this, for now just join [the chat](#chat) and ask about graphic design.
|
||||
127
README.md
127
README.md
|
|
@ -1,69 +1,108 @@
|
|||
# kernel
|
||||
<img alt="Redox" height="90" src="https://github.com/redox-os/assets/raw/master/logo.png">
|
||||
|
||||
A collaborative effort to rewrite the kernel with focus on correctness and code
|
||||
quality.
|
||||
**Redox** is an operating system written in pure Rust, designed to be secure and free. The website can be found at https://www.redox-os.org.
|
||||
|
||||
## Why?
|
||||
Documentation can be found [here](https://doc.redox-os.org/doc/std/).
|
||||
|
||||
The kernel code was getting increasingly messy to the point where only the
|
||||
original writer would be able to find and fix bugs. Fortunately, the kernel of
|
||||
Redox is relatively small and such a project is estimated to take only a few
|
||||
months.
|
||||
Please make sure you use the **latest nightly** of `rustc` before building (for more troubleshooting, see ["Help! Redox won't compile!"](#compile-help)).
|
||||
|
||||
## What?
|
||||
[](https://travis-ci.org/redox-os/redox)
|
||||
[](./LICENSE.md)
|
||||
|
||||
The aims of the new kernel should be clear in their order:
|
||||
## Contents
|
||||
|
||||
1. **Correctness**: Above anything else, the kernel should be correct. No hacks,
|
||||
despite how the tiny cool shortcuts might seem, it gives severe backslash later
|
||||
on. Keep it correct and well-written.
|
||||
* [What it looks like](#what-it-looks-like)
|
||||
* [Help! Redox won't compile](#compile-help)
|
||||
* [Contributing to Redox](#contributing)
|
||||
* [Cloning, Building and running](#cloning-building-running)
|
||||
* [Quick Setup](#quick-setup)
|
||||
* [Manual Setup](#manual-setup)
|
||||
|
||||
2. **Readability and documentation**: The code quality should be high, with that
|
||||
follows a detailed documentation, including both API docs (on every item!) and
|
||||
careful comments for anything non-trivial.
|
||||
|
||||
3. **Performance**: If you can, go for it.
|
||||
## <a name="what-it-looks-like"> What it looks like </a>
|
||||
|
||||
## Guidelines
|
||||
<img alt="Redox" height="150" src="https://github.com/redox-os/assets/raw/master/screenshots/Desktop.png">
|
||||
<img alt="Redox" height="150" src="https://github.com/redox-os/assets/raw/master/screenshots/Fancy_opacity.png">
|
||||
<img alt="Redox" height="150" src="https://github.com/redox-os/assets/raw/master/screenshots/File_manager.png">
|
||||
|
||||
### A rotten house is built on a rotten fundament.
|
||||
<img alt="Redox" height="150" src="https://github.com/redox-os/assets/raw/master/screenshots/Sodium_v1.png">
|
||||
<img alt="Redox" height="150" src="https://github.com/redox-os/assets/raw/master/screenshots/Boot.png">
|
||||
<img alt="Redox" height="150" src="https://github.com/redox-os/assets/raw/master/screenshots/start.png">
|
||||
|
||||
Don't fool yourself. You are likely not getting back to the ugly code. Write it
|
||||
the right way **first time**, and make sure you only move on when it's
|
||||
**done right**.
|
||||
## <a name="compile-help"> Help! Redox won't compile! </a>
|
||||
|
||||
### Comments
|
||||
Sometimes things go wrong when compiling. Try the following before opening an issue:
|
||||
|
||||
Do not hesitate to put comments all over the place.
|
||||
1. Run `make clean`.
|
||||
2. Run `git clean -X -f -d`.
|
||||
3. Make sure you have **the latest version of Rust nightly!** ([rustup.rs](https://www.rustup.rs) is recommended for managing Rust versions).
|
||||
4. Update **GNU Make**, **NASM** and **QEMU/VirtualBox**.
|
||||
5. Pull the upstream master branch (`git remote add upstream git@github.com:redox-os/redox.git; git pull upstream master`).
|
||||
6. Update submodules (`git submodule update --recursive --init`).
|
||||
|
||||
### Documentation
|
||||
and then rebuild!
|
||||
|
||||
Every public item should contain API documentation.
|
||||
## <a name="contributing"> Contributing to Redox </a>
|
||||
|
||||
### Debug assertions
|
||||
If you're interested in this project, and you'd like to help us out, [here](CONTRIBUTING.md) is a list of ways you can do just that.
|
||||
|
||||
Abusing debug assertions is a wonderful way to catch bugs, and it is very much
|
||||
encouraged.
|
||||
## <a name="cloning-building-running"> Cloning, Building, and Running </a>
|
||||
|
||||
### Statical checking
|
||||
Redox is big (even compressed)! So cloning Redox takes a lot of bandwidth, and (depending on your data plan) can be costly, so clone at your own risk!
|
||||
|
||||
Rust provides a lot of type-system features which can be used to create
|
||||
wonderful safe abstractions, and you should use them whenever you get the chance.
|
||||
### <a name="quick-setup" /> Quick Setup </a>
|
||||
|
||||
Unsafety should be avoided, and if it is triggered only under some addition
|
||||
**insert an assertion**. Despite this being a kernel, we prefer kernel panics
|
||||
over security vulnerabilities.
|
||||
```bash
|
||||
$ cd path/to/your/projects/folder/
|
||||
|
||||
If the condition is (or should be) unreachable, but if not upheld, leading to
|
||||
UB, put an assertion in the start of the function.
|
||||
# Run bootstrap setup
|
||||
$ curl -sf https://raw.githubusercontent.com/redox-os/redox/master/bootstrap.sh -o bootstrap.sh && bash -e bootstrap.sh
|
||||
|
||||
### Be gentle
|
||||
# Build Redox
|
||||
$ make all
|
||||
|
||||
Don't just write as much code as you can as quick as possible. Take your time
|
||||
and be careful.
|
||||
# Launch using QEMU
|
||||
$ make qemu
|
||||
# Launch using QEMU without using KVM (Kernel Virtual Machine). Try if QEMU gives an error.
|
||||
$ make qemu kvm=no
|
||||
```
|
||||
|
||||
### Commits
|
||||
#### QEMU with KVM
|
||||
|
||||
Use descriptive commits. One way to force yourself to do that is to not pass the
|
||||
`-m` flag, which will make your editor pop up, so that you can conviniently
|
||||
write long commit messages.
|
||||
To use QEMU with KVM (kernel-based virtual Machine), which is faster than without KVM, you need a CPU with Intel® Virtualization Technology (Intel® VT) or AMD Virtualization™ (AMD-V™) support. Most systems have this disabled in the BIOS by default, so you may need to reboot and enable the feature in the BIOS.
|
||||
|
||||
### <a name="manual-setup"> Manual Setup </a>
|
||||
|
||||
To manually clone, build and run Redox using a Linux host, run the following commands (with exceptions, be sure to read the comments):
|
||||
```bash
|
||||
$ cd path/to/your/projects/folder/
|
||||
|
||||
# HTTPS
|
||||
$ git clone https://github.com/redox-os/redox.git --origin upstream --recursive
|
||||
# SSH
|
||||
$ git clone git@github.com:redox-os/redox.git --origin upstream --recursive
|
||||
|
||||
$ cd redox/
|
||||
|
||||
# Install/update dependencies
|
||||
$ sudo <your package manager> install make nasm qemu libfuse-dev
|
||||
|
||||
# Install rustup.rs
|
||||
$ curl https://sh.rustup.rs -sSf | sh
|
||||
|
||||
# Set override toolchain to nightly build
|
||||
$ rustup override set nightly
|
||||
|
||||
# For successive builds start here. If this is your first build, just continue
|
||||
|
||||
# Update git submodules
|
||||
$ git submodule update --recursive --init
|
||||
|
||||
# Build Redox
|
||||
$ make all
|
||||
|
||||
# Launch using QEMU
|
||||
$ make qemu
|
||||
# Launch using QEMU without using KVM (Kernel Virtual Machine). Try if QEMU gives an error.
|
||||
$ make qemu kvm=no
|
||||
```
|
||||
|
|
|
|||
69
kernel/README.md
Normal file
69
kernel/README.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
# kernel
|
||||
|
||||
A collaborative effort to rewrite the kernel with focus on correctness and code
|
||||
quality.
|
||||
|
||||
## Why?
|
||||
|
||||
The kernel code was getting increasingly messy to the point where only the
|
||||
original writer would be able to find and fix bugs. Fortunately, the kernel of
|
||||
Redox is relatively small and such a project is estimated to take only a few
|
||||
months.
|
||||
|
||||
## What?
|
||||
|
||||
The aims of the new kernel should be clear in their order:
|
||||
|
||||
1. **Correctness**: Above anything else, the kernel should be correct. No hacks,
|
||||
despite how the tiny cool shortcuts might seem, it gives severe backslash later
|
||||
on. Keep it correct and well-written.
|
||||
|
||||
2. **Readability and documentation**: The code quality should be high, with that
|
||||
follows a detailed documentation, including both API docs (on every item!) and
|
||||
careful comments for anything non-trivial.
|
||||
|
||||
3. **Performance**: If you can, go for it.
|
||||
|
||||
## Guidelines
|
||||
|
||||
### A rotten house is built on a rotten fundament.
|
||||
|
||||
Don't fool yourself. You are likely not getting back to the ugly code. Write it
|
||||
the right way **first time**, and make sure you only move on when it's
|
||||
**done right**.
|
||||
|
||||
### Comments
|
||||
|
||||
Do not hesitate to put comments all over the place.
|
||||
|
||||
### Documentation
|
||||
|
||||
Every public item should contain API documentation.
|
||||
|
||||
### Debug assertions
|
||||
|
||||
Abusing debug assertions is a wonderful way to catch bugs, and it is very much
|
||||
encouraged.
|
||||
|
||||
### Statical checking
|
||||
|
||||
Rust provides a lot of type-system features which can be used to create
|
||||
wonderful safe abstractions, and you should use them whenever you get the chance.
|
||||
|
||||
Unsafety should be avoided, and if it is triggered only under some addition
|
||||
**insert an assertion**. Despite this being a kernel, we prefer kernel panics
|
||||
over security vulnerabilities.
|
||||
|
||||
If the condition is (or should be) unreachable, but if not upheld, leading to
|
||||
UB, put an assertion in the start of the function.
|
||||
|
||||
### Be gentle
|
||||
|
||||
Don't just write as much code as you can as quick as possible. Take your time
|
||||
and be careful.
|
||||
|
||||
### Commits
|
||||
|
||||
Use descriptive commits. One way to force yourself to do that is to not pass the
|
||||
`-m` flag, which will make your editor pop up, so that you can conviniently
|
||||
write long commit messages.
|
||||
Loading…
Reference in a new issue