diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c8dc0e..0689b42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ # Contributing to Sprout -Welcome! We're very glad you're reading this; Edera is excited for all kinds of contributions! Please read the following to ensure you're aware of our flow and policies. +Welcome! We're happy you're reading this; Edera is excited for all kinds of contributions! Please read the following to ensure you're aware of our flow and policies. -## Before contributing +## Before Contributing 1. Please read our [Code of Conduct](CODE_OF_CONDUCT.md), which applies to all interactions in/with all Edera projects and venues. 2. Before opening an issue or PR, please try a few searches to see if there is overlap with existing conversations or WIP contributions. @@ -11,7 +11,7 @@ Welcome! We're very glad you're reading this; Edera is excited for all kinds of ## Contributing Code -To get started with technical contributions, please read out [Development Guide]. If you're looking for something easy to tackle, [look for issues labeled `good first issue`][good-first-issue]. +To get started with technical contributions, please read out [Development Guide]. If you're looking for something easy to tackle, [look for issues labeled `good first issue`][good-first-issues]. ## Reporting bugs and other issues @@ -20,13 +20,13 @@ We encourage opening an issue on GitHub to report bugs. ## Pull Requests 1. For anything more than simple bug/doc fixes, please open a GitHub issue for tracking purposes. - - Else skip to step 3. 2. Discuss the change with the teams to ensure we have consensus on the change being welcome. 3. We encourage opening the PR sooner than later, and prefixing with `WIP:` so GitHub labels it as a Draft. 4. Please include a detailed list of changes that the PR makes. 5. Once the PR is ready for review, remove the Draft status, and request a review from `edera-dev/engineering`. -6. After the review cycle concludes and we know you are ready for merging, a team member will submit the PR to the merge queue. +6. After the review cycle concludes, and we know you are ready for merging, a team member will submit the PR to the merge queue. [Code of Conduct]: ./CODE_OF_CONDUCT.md +[Development Guide]: ./DEVELOPMENT.md [Security Policy]: ./SECURITY.md [good-first-issues]: https://github.com/edera-dev/sprout/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..63145c1 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,51 @@ +# Sprout Development Guide + +This guide is a work in progress. + +## Development Setup + +You can use any Rust development environment to develop Sprout. + +Rustup is recommended as the Rust toolchain manager to manage Rust versions and targets. + +Sprout currently requires Rust nightly to support uefi_std. See [uefi_std](https://doc.rust-lang.org/beta/rustc/platform-support/unknown-uefi.html) for more details. + +We currently only support `x86_64-unknown-uefi` and `aarch64-unknown-uefi` targets. + +To test your changes in QEMU, please run `./hack/dev/boot.sh`, you can specify `x86_64` or `aarch64` +as an argument to boot.sh to boot the specified architecture. + +## Hack Scripts + +You can use the `./hack` scripts to run common development tasks: + +### ./hack/build.sh + +Builds the Sprout binary for the target that would support your current machine. + +### ./hack/assemble.sh + +Builds both x86_64 and aarch64 binaries into `target/assemble`. + +### ./hack/clean.sh + +Cleans the target directory and any docker images that were built. + +### ./hack/format.sh + +Formats the code using `rustfmt` and shell scripts with `shfmt`. + +### ./hack/autofix.sh + +Applies Clippy and `rustfmt` fixes to the code, and formats shell scripts with `shfmt`. + +## Dev Scripts + +### ./hack/dev/build.sh + +Build Sprout as OCI images using Docker, including a kernel, initramfs, xen, and other supporting files. + +### ./hack/dev/boot.sh + +Boot Sprout's dev environment using QEMU for testing. This will let you test your changes in a real environment booting +Alpine Linux with an initramfs.