Commit 55f3338a authored by Ben Elliott's avatar Ben Elliott Committed by Jeremy Soller

Added Documentation For Contributors (#55)

This contribution adds information for contributors (which fills
in some missing sections in the book). Meta!

I copied a lot of this from the main Redox project's CONTRIBUTING.md,
with minimal changes where appropriate. Also, some small additions.
parent 36a6a831
......@@ -111,38 +111,37 @@
-------------------------------------------------------------------------------
- [Contributing]()
- [Contributing](./contributing/contributing.md)
- [Communication]()
- [Chat](./contributing/chat.md)
- [Chat](./contributing/communication/chat.md)
- [Reddit](./contributing/communication/reddit.md)
- [Direct contributions]()
- [Low hanging fruit]()
- [Github issues]()
- [How to do a bug report correctly]()
- [Pull requests]()
- [How to do a pull request properly]()
- [Low hanging fruit](./contributing/direct_contributions/low_hanging_fruit.md)
- [Github issues](./contributing/direct_contributions/github_issues.md)
- [How to do a bug report correctly](./contributing/direct_contributions/creating_proper_bug_reports.md)
- [Pull requests](./contributing/direct_contributions/pull_requests.md)
- [How to do a pull request properly](./contributing/direct_contributions/creating_proper_pull_requests.md)
- [Indirect contributions]()
- [Community]()
- [Community](./contributing/indirect_contributions/community.md)
- [Porting your programs to Redox]()
- [Best practices and guidelines]()
- [Best practices and guidelines](./contributing/best_practices/overview.md)
- [Documentation]()
- [Literal programming]()
- [Writing docs correcty (TM)]()
- [Literate programming](./contributing/documentation/literate_programming.md)
- [Writing docs correcty (TM)](./contributing/documentation/writing_docs_correctly.md)
- [Marking code]()
- [XXX]()
- [TODO]()
- [FIXME]()
- [Style]()
- [Rusting properly]()
- [Style](./contributing/best_practices/style.md)
- [Rusting properly](./contributing/best_practices/rusting_properly.md)
- [Writing fast Rust]()
- [Avoiding heap allocations]()
- [Exiting a program]()
- [Avoiding panics in the kernel]()
- [Avoiding panics in the kernel](./contributing/best_practices/avoiding_kernel_panics.md)
- [Tests]()
- [Tests in the kernel]()
- [Logging and assertions]()
- [Git]()
- [Writing an issue]()
- [Documenting your changes]()
- [Git](./contributing/best_practices/git.md)
- [Understanding the codebase]()
- [Kernel]()
......
# Avoiding Kernel Panics
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.
# Git Guidelines
* 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.
# Best Practices and Guidelines
These are a set of best practices to keep in mind when making a contribution to Redox. As always, rules are made to be broken, but these rules in particular play a part in deciding whether to merge your contribution (or not). So do try to follow them.
# Rusting Properly
Some general guidelines:
* 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.
# Rust Style
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.
# Chat
The quickest and most open way to communicate with the Redox team is on our [Mattermost](https://www.mattermost.org/) 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.
The quickest and most open way to communicate with the Redox team is on our [Mattermost](https://www.mattermost.org/) 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.
# Reddit
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.
# Contributing
So you'd like to contribute to make Redox better! Excellent. This chapter can help you to do just that.
# Creating a Proper Bug Report
1. Make sure the code you are seeing the issue with is up to date with `upstream/master`. This helps to weed out reports for bugs that have already been addressed.
2. Make sure the issue is reproducible (trigger it several times). If the issue happens inconsistently, it may still be worth filing a bug report for it, but indicate approximately how often the bug occurs
3. Record build information like:
* The rust toolchain you used to build Redox
* `rustc -V` and/or `rustup show` from your Redox project folder
* The commit hash of the code you used
* `git rev-parse HEAD`
* The environment you are running Redox in (the "target")
* `qemu-i386 -version` or your actual hardware specs, if applicable
* The operating system you used to build Redox
* `uname -a` or an alternative format
4. Make sure that your bug doesn't already have an issue on Github. If you submit a duplicate, you should accept that you may be ridiculed for it, though you'll still be helped. Feel free to ask in the Redox [chat](./contributing/communication/chat.html) if you're uncertain as to whether your issue is new
5. Create a Github issue following the template
* Non-bug report issues may ignore this template
6. Watch the issue and be available for questions
7. Success!
With the help of fellow Redoxers, legitimate bugs can be kept to a low simmer, not a boil.
# Creating a Proper Pull Request
The steps given below are for the main Redox project - submodules and other projects may vary, though most of the approach is the same.
1. 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`
* Use HTTPS if you don't know which one to use. (Recommended: learn about SSH if you don't want to have to login every time you push/pull!)
2. Then rebase to ensure you're using the latest changes: `git rebase upstream master`
3. Fork the repository
4. Add your fork to your list of git remotes 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`
5. 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`
6. Optionally create a separate branch (recommended if you're making multiple changes simultaneously) (`git checkout -b my-branch`)
7. Make changes
8. Commit (`git add . --all; git commit -m "my commit"`)
9. 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)
10. 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](./contributing/best_practices/overview.html))
11. 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.)
12. Repeat step 9 to make sure the rebase still builds and starts
13. Push to your fork (`git push origin my-branch`)
14. Create a pull request, following the template
15. Describe your changes
16. Submit!
# GitHub Issues
Github issues are a somewhat formal way to communicate with fellow Redox devs, but a little less quick and convenient than the chat. Issues are a good way to discuss specific topics, but if you want a quick response, using the chat is probably better.
If you haven't requested to join the chat yet, you should (if at all interested in contributing)!
# Low-Hanging Fruit
## aka Easy Targets for Newbies, Quick Wins for Pros
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
# Pull Requests
It's completely fine to just submit a small pull request without first making an issue, but if it's a big change that will require a lot of planning and reviewing, it's best you start with writing an issue first. Also see the [git guidelines](./contributing/best_practices/git.html).
# Literate programming
Literate programming is an approach to programming where the source code serves equally as:
- The complete description of the program, that a computer can understand
- The program's manual for the human, that an *average* human can understand
Literate programs are written in such a way that humans can read them from front to back, and understand the entire purpose and operation of the program without preexisting knowledge about the programming language used, the architecture of the program's components, or the intended use of the program. As such, literate programs tend to have lots of clear and well-written comments. In extreme cases of literate programming, the lines of "code" intended for humans far outnumbers the lines of code that actually gets compiled!
Tools can be used to generate documentation for human use only based on the original source code of a program. The `rustdoc` tool is a good example of such a tool. In particular, `rustdoc` uses comments with three slashes `///`, with special sections like `# Examples` and code blocks bounded by three backticks. The code blocks can be used to writeout examples or unit tests inside of comments. You can read more about `rustdoc` [here](https://doc.rust-lang.org/stable/book/documentation.html).
# Writing Documentation Correctly (TM)
Documentation for Redox appears in two places:
- In the source code
- On the website (the Redox Book and online API documentation)
Redox functions and modules should use `rustdoc` annotations where possible, as they can be used to generate online API documentation - this ensures uniform documentation between those two halves. In particular, this is more strictly required for public APIs; internal functions can generally eschew them (though having explanations for any code can still help newcomers to understand the codebase). When in doubt, making code more literate is better, so long as it doesn't negatively affect the functionality. Run `rustdoc` against any added documentation of this type before submitting them to check for correctness, errors, or odd formatting.
Documentation for the Redox Book generally should not include API documentation directly, but rather cover higher-level overviews of the entire codebase, project, and community. It is better to have information in the Book than not to have it, so long as it is accurate, relevant, and well-written. When writing documentation for the Book, be sure to run `mdbook` against any changes to test the results before submitting them.
# Community
Community outreach is an important part of Redox's success. If more people know about Redox, then more contributors are likely to step in, and everyone can benefit from their added expertise. You can make a difference by writing articles, talking to fellow OS enthusiasts, or looking for communities that would be interested in knowing more about Redox.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment