From f42a7ebb168aee3cf3c7a8487882438413347e7e Mon Sep 17 00:00:00 2001 From: Ribbon Date: Mon, 27 Feb 2023 19:42:16 +0000 Subject: [PATCH 1/4] Cleanup CONTRIBUTING (deduplication/old stuff). --- CONTRIBUTING.md | 85 ++----------------------------------------------- 1 file changed, 3 insertions(+), 82 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 91a87b6..66e4484 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,11 +8,7 @@ _**Thank you for your interest in contributing to Redox!** This document will ou * [Chat](#chat) * [GitLab Issues](#issues) * [Pull Requests](#prs) - * [Discourse](#discourse) - * [Reddit](#reddit) - * [News](#news) -* [Code Contributions](#code-contributions) - * [Low-Hanging Fruit - Easy Targets for Newbies](#easy-targets) +* [Low-Hanging Fruit - Easy Targets for Newbies](#easy-targets) * [Best Practices/Guidelines](#best-practices) * [General](#general) * [Kernel](#kernel) @@ -22,7 +18,6 @@ _**Thank you for your interest in contributing to Redox!** This document will ou * [Git](#git-style-guidelines) * [Other Ways to Contribute](#other) * [Graphic Design](#graphic-design) - * [Patreon](#patreon) ## Other External Links @@ -48,42 +43,6 @@ A bit more formal way of communication with fellow Redox devs, but a little less [How to make pull requests properly]: https://doc.redox-os.org/book/ch12-04-creating-proper-pull-requests.html -### Discourse - -We have a **discourse forum** at [discourse.redox-os.org](https://discourse.redox-os.org). This is the best way to discuss more general topics that aren't about specific things that need to be addressed one way or another. You can sign up like any other website. - -### Reddit - -You can also find **Redox on Reddit** in [/r/rust/](https://www.reddit.com/r/rust) and [/r/redox/](https://www.reddit.com/r/redox). Redox news and discussion is posted on the latter, and Rust news and discussion, as well as some Redox posts, is on the former. - -### News - -News and updates for Redox are posted at [redox-os.org/news](https://redox-os.org/news). It's more one-way than the other things on this list, but it should provide a good summary of what's been going on with the project lately. It's usually updated weekly, but with some exceptions. A mailing list may be included eventually, but it's not set up right now. - -## Code Contributions - -### Low-Hanging Fruit - Easy Targets for Newbies - -#### 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://gitlab.redox-os.org/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://gitlab.redox-os.org/redox-os/ion)) development - * **Package management** ([pkgutils](https://gitlab.redox-os.org/redox-os/pkgutils)) 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** - ## Best Practices and Guidelines ### General @@ -93,23 +52,6 @@ News and updates for Redox are posted at [redox-os.org/news](https://redox-os.or * **Don't hesitate to ask for help, comments or suggestions!** * **Before implementing something, discuss it! Open an issue, or ask in the chat.** -##### On the more technical side: -* Test, test, and test! -* Follow the style conventions (See [rust style guidelines](#rust-style-guidelines)) -* Use `std::mem::replace` and `std::mem::swap` when you can. -* `libredox` should be 1-to-1 with the official `libstd`. -* Prefer `.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` 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 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. **Longer safe code is better than shorter unsafe code!** -* Be sure to mark parts that need work with `TODO`, `FIXME`, `BUG`, `UNOPTIMIZED`, `REWRITEME`, `DOCME`, and `PRETTYFYME`. Always elaborate on these messages, too. Nothing is more annoying than seeing a `TODO` and not knowing how to actually fix it. -* 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/news), and [the Rust subreddit](https://www.reddit.com/r/rust) frequently. - ### Kernel * 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. @@ -122,11 +64,6 @@ News and updates for Redox are posted at [redox-os.org/news](https://redox-os.or Even though Rust is a safety-oriented language, something as unstable and low-level as an in-dev operating system will almost certainly 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. - ## Style Guidelines ### Rust @@ -135,9 +72,9 @@ Since **Rust** is a relatively small and new language compared to others like _C ### Git -* 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. +* You should have a fork of the repository on **GitLab** and a local copy on your computer. The local copy should have two remotes; `origin` and `fork`, `origin` should be set to the main repository and `fork` should be your fork. * 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. -* Usually, when syncing your local copy with the master branch, you'll 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. You can do this in one command with `git pull upstream --rebase`. This will pull from the upstream, then roll back to the current state of the upstream, and "replay" your changes on top of it. Make sure you commit before doing this, though. Git won't be able to rebase if you don't. +* Usually, when syncing your local copy with the master branch, you'll 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. You can do this in one command with `git pull origin --rebase`. This will pull from the upstream, then roll back to the current state of the upstream, and "replay" your changes on top of it. Make sure you commit before doing this, though. Git won't be able to rebase if you don't. * Prefer to omit the `-m` when using `git commit`. This opens your editor and should help get you in the habit of writing longer commit messages. * Commit messages should describe their changes in present tense, e.g. "`Add stuff to file.ext`" instead of "`added stuff to file.ext`". This makes sense as sometimes when you revert back, then run through commits one-by-one, you want to see what a commit will do, instead of just what the person did when they made the commit. It's also just being consistent. * Try to remove useless duplicate/merge commits from PRs as these don't do anything except clutter up history and make it harder to read. @@ -149,19 +86,3 @@ If you're not big on coding, but you still want to help keep the project going, ### Design If you're a good designer, whether it's _2D graphics, 3D graphics, interfaces, web design, you can help. We need logos, UI design, UI skins, app icons, desktop backgrounds, etc_. More information to come on this in the future, for now just join [the chat](#chat) and ask about graphic design. - -### Patreon - -Our **BDFL**, [jackpot51](https://gitlab.redox-os.org/jackpot51), has a [Patreon campaign](https://www.patreon.com/redox_os)! **All money received will go towards Redox OS development**. If you donate, you will be listed in the **Redox credits** as one of the people that made Redox OS possible. You'll also get other rewards the more you donate. However, please don't donate if you can't afford it. - - - From 84f87c289271b2d4a60c1547518fbba036b0ae27 Mon Sep 17 00:00:00 2001 From: Ribbon Date: Tue, 28 Feb 2023 08:18:45 +0000 Subject: [PATCH 2/4] Remove kernel section/HTML syntax and update internal hyperlinks. --- CONTRIBUTING.md | 46 +++++++++++++++++++--------------------------- 1 file changed, 19 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66e4484..0a1f3b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,28 +6,26 @@ _**Thank you for your interest in contributing to Redox!** This document will ou * [Communication](#communication) * [Chat](#chat) - * [GitLab Issues](#issues) - * [Pull Requests](#prs) -* [Low-Hanging Fruit - Easy Targets for Newbies](#easy-targets) -* [Best Practices/Guidelines](#best-practices) + * [GitLab Issues](#gitlab-issues) + * [Pull Requests](#pull-requests) +* [Best Practices/Guidelines](#best-practices-and-guidelines) * [General](#general) - * [Kernel](#kernel) * [Testing Practices](#testing-practices) * [Style Guidelines](#style-guidelines) - * [Rust](#rust-style-guidelines) + * [Rust](#rust) * [Git](#git-style-guidelines) -* [Other Ways to Contribute](#other) - * [Graphic Design](#graphic-design) +* [Other Ways to Contribute](#other-ways-to-contribute) + * [Design](#design) -## Other External Links +## Other External Links * [redox-os.org](https://redox-os.org) * [rust-os-comparison](https://github.com/flosse/rust-os-comparison) * [rust-lang.org](http://rust-lang.org) -## Communication +## Communication -### Chat +### Chat - [Redox Dev room] - [Redox Support room] @@ -35,42 +33,36 @@ _**Thank you for your interest in contributing to Redox!** This document will ou [Redox Dev room]: https://matrix.to/#/#redox-dev:matrix.org [Redox Support room]: https://matrix.to/#/#redox-support:matrix.org -### GitLab Issues +### GitLab Issues A bit more formal way of communication with fellow Redox devs, but a little less quick and convenient like the chat. Submit an issue when you run into problems compiling, testing, or just would like to discuss a certain topic, be it _features, code style, code inconsistencies, minor changes and fixes, etc._ -### Pull Requests +### Pull Requests [How to make pull requests properly]: https://doc.redox-os.org/book/ch12-04-creating-proper-pull-requests.html -## Best Practices and Guidelines +## Best Practices and Guidelines -### General +### General * **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, comments or suggestions!** * **Before implementing something, discuss it! Open an issue, or ask in the chat.** -### Kernel - -* 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. - -### Testing Practices +### Testing Practices * 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 and low-level as an in-dev operating system will almost certainly 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. -## Style Guidelines +## Style Guidelines -### Rust +### Rust 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. -### Git +### Git * You should have a fork of the repository on **GitLab** and a local copy on your computer. The local copy should have two remotes; `origin` and `fork`, `origin` should be set to the main repository and `fork` should be your fork. * 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. @@ -79,10 +71,10 @@ Since **Rust** is a relatively small and new language compared to others like _C * Commit messages should describe their changes in present tense, e.g. "`Add stuff to file.ext`" instead of "`added stuff to file.ext`". This makes sense as sometimes when you revert back, then run through commits one-by-one, you want to see what a commit will do, instead of just what the person did when they made the commit. It's also just being consistent. * Try to remove useless duplicate/merge commits from PRs as these don't do anything except clutter up history and make it harder to read. -## Other Ways to Contribute +## Other Ways to Contribute If you're not big on coding, but you still want to help keep the project going, you can still contribute/support in a variety of ways! We'll try to find a way to use anything you have to offer. -### Design +### Design If you're a good designer, whether it's _2D graphics, 3D graphics, interfaces, web design, you can help. We need logos, UI design, UI skins, app icons, desktop backgrounds, etc_. More information to come on this in the future, for now just join [the chat](#chat) and ask about graphic design. From 0f4a97e919a3c41b8a7442bae6215c9ba2e2cade Mon Sep 17 00:00:00 2001 From: Ribbon Date: Tue, 28 Feb 2023 08:52:59 +0000 Subject: [PATCH 3/4] More cleanup/improvements. --- CONTRIBUTING.md | 71 +++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a1f3b3..42c3125 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,18 +4,21 @@ _**Thank you for your interest in contributing to Redox!** This document will ou ## Index -* [Communication](#communication) - * [Chat](#chat) - * [GitLab Issues](#gitlab-issues) - * [Pull Requests](#pull-requests) -* [Best Practices/Guidelines](#best-practices-and-guidelines) - * [General](#general) - * [Testing Practices](#testing-practices) -* [Style Guidelines](#style-guidelines) - * [Rust](#rust) - * [Git](#git-style-guidelines) -* [Other Ways to Contribute](#other-ways-to-contribute) - * [Design](#design) +- [Code Of Conduct](#code-of-conduct) +- [Communication](#communication) + - [Chat](#chat) + - [GitLab Issues](#gitlab-issues) + - [Pull Requests](#pull-requests) +- [Low-Hanging Fruit - Easy Targets for Newbies](#low-hanging-fruit-easy-targets-for-newbies) +- [Best Practices/Guidelines](#best-practices-and-guidelines) + - [General](#general) + - [Testing Practices](#testing-practices) +- [Style Guidelines](#style-guidelines) + - [Rust](#rust) + - [Git](#git) +- [Other Ways to Contribute](#other-ways-to-contribute) + - [Design](#design) + - [Donate to Redox](#donate-to-redox) ## Other External Links @@ -23,38 +26,37 @@ _**Thank you for your interest in contributing to Redox!** This document will ou * [rust-os-comparison](https://github.com/flosse/rust-os-comparison) * [rust-lang.org](http://rust-lang.org) +## Code Of Conduct + +We follow the [Rust Code Of Conduct](https://www.rust-lang.org/policies/code-of-conduct). + ## Communication ### Chat -- [Redox Dev room] -- [Redox Support room] - -[Redox Dev room]: https://matrix.to/#/#redox-dev:matrix.org -[Redox Support room]: https://matrix.to/#/#redox-support:matrix.org +Join us on [Matrix Chat](https://doc.redox-os.org/book/ch13-01-chat.html) to discuss issues or ask questions. ### GitLab Issues -A bit more formal way of communication with fellow Redox devs, but a little less quick and convenient like the chat. Submit an issue when you run into problems compiling, testing, or just would like to discuss a certain topic, be it _features, code style, code inconsistencies, minor changes and fixes, etc._ +You will need to have a Redox GitLab account to file an issue, and registration can take a few days. + +- [Redox Book Guide](https://doc.redox-os.org/book/ch13-03-gitlab-issues.html) ### Pull Requests -[How to make pull requests properly]: https://doc.redox-os.org/book/ch12-04-creating-proper-pull-requests.html +Please follow our process for [creating proper pull requests](https://doc.redox-os.org/book/ch12-04-creating-proper-pull-requests.html). + +## Low-Hanging Fruit - Easy Targets for Newbies + +- [Redox Book Guide](https://doc.redox-os.org/book/ch10-02-low-hanging-fruit.html) ## Best Practices and Guidelines -### General - -* **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, comments or suggestions!** -* **Before implementing something, discuss it! Open an issue, or ask in the chat.** +- [Redox Book Guide](https://doc.redox-os.org/book/ch11-00-best-practices.html) ### Testing Practices -* 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 and low-level as an in-dev operating system will almost certainly 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. +- [Redox Book Guide](https://doc.redox-os.org/book/ch09-03-testing-practices.html) ## Style Guidelines @@ -64,12 +66,7 @@ Since **Rust** is a relatively small and new language compared to others like _C ### Git -* You should have a fork of the repository on **GitLab** and a local copy on your computer. The local copy should have two remotes; `origin` and `fork`, `origin` should be set to the main repository and `fork` should be your fork. -* 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. -* Usually, when syncing your local copy with the master branch, you'll 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. You can do this in one command with `git pull origin --rebase`. This will pull from the upstream, then roll back to the current state of the upstream, and "replay" your changes on top of it. Make sure you commit before doing this, though. Git won't be able to rebase if you don't. -* Prefer to omit the `-m` when using `git commit`. This opens your editor and should help get you in the habit of writing longer commit messages. -* Commit messages should describe their changes in present tense, e.g. "`Add stuff to file.ext`" instead of "`added stuff to file.ext`". This makes sense as sometimes when you revert back, then run through commits one-by-one, you want to see what a commit will do, instead of just what the person did when they made the commit. It's also just being consistent. -* Try to remove useless duplicate/merge commits from PRs as these don't do anything except clutter up history and make it harder to read. +Please follow [how to create a proper pull request](https://doc.redox-os.org/book/ch12-04-creating-proper-pull-requests.html). ## Other Ways to Contribute @@ -77,4 +74,8 @@ If you're not big on coding, but you still want to help keep the project going, ### Design -If you're a good designer, whether it's _2D graphics, 3D graphics, interfaces, web design, you can help. We need logos, UI design, UI skins, app icons, desktop backgrounds, etc_. More information to come on this in the future, for now just join [the chat](#chat) and ask about graphic design. +If you're a good designer, whether it's _2D graphics, 3D graphics, interfaces, web design, you can help. We need logos, UI design, UI skins, app icons, desktop backgrounds, etc_. More information to come on this in the future, for now just join the [Chat](https://doc.redox-os.org/book/ch13-01-chat.html) and ask about graphic design. + +### Donate to Redox + +If you are interested in donating to the Redox OS nonprofit, you can find instructions [here](https://www.redox-os.org/donate/). From 65687a1962de8fcd844b5779dc2742eb4e81cddb Mon Sep 17 00:00:00 2001 From: Ribbon Date: Tue, 28 Feb 2023 09:23:53 +0000 Subject: [PATCH 4/4] Add a "License" section. --- CONTRIBUTING.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42c3125..cadd29b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,7 @@ _**Thank you for your interest in contributing to Redox!** This document will ou ## Index - [Code Of Conduct](#code-of-conduct) +- [License](#license) - [Communication](#communication) - [Chat](#chat) - [GitLab Issues](#gitlab-issues) @@ -30,6 +31,12 @@ _**Thank you for your interest in contributing to Redox!** This document will ou We follow the [Rust Code Of Conduct](https://www.rust-lang.org/policies/code-of-conduct). +## License + +All contributions are under the MIT license. + +- [Our Philosophy](https://doc.redox-os.org/book/ch01-02-philosophy.html) + ## Communication ### Chat