Skip to content

Latest commit

 

History

History
104 lines (67 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

104 lines (67 loc) · 5.26 KB

Contributing Guidelines

Thank you for your interest in contributing to High Assurance Rust!

Your efforts make the book better for all other readers and are greatly appreciated.

Contributions We Accept

  • Grammar, Spelling, Capitalization, or Punctuation Errors: Anything objectively wrong in the English language.

  • Factual or Technical Errors: Anything provably incorrect. A counterexample or citation is recommended, but not required.

    • Please open an Issue explaining the error found.

  • Docker and CI Improvements: Anything related to the testing or maintenance of this book's Docker container.

  • Formatting Fixes: Almost every diagram in this book was created using diagrams.net and there may be SVG rendering issues on mobile, with different browsers or font settings, etc. Text content could also be subject to device-specific formatting issues.

    • Please open a Pull Request (PR) with the fix or update. If it fixes your formatting issue and still works on our version of Firefox on Linux desktop, we'll accept it!

Contributions We Cannot Accept

Anything outside of the above, including: rewording for style or clarity, addition of new content, removal of existing content, etc.

These kinds of changes tend to be subjective and require back-and-forth collaboration to reach consensus. We'd like to maintain a consistent voice.

If you'd like to suggest a content revision, have any questions about contributing not answered by this guide, or do not wish to use GitHub for any reason, please reach out via email:

[email protected]

These contributing guidelines are not set in stone, we're very much "learning as we go". If there's a change to the contribution model that'd make this project better in the long-term, please feel free to suggest it via email or GitHub issue!

Files to Change in a PR

Please only modify .md, .rs, or .svg files. We'll generate the book using a local copy of the mdbook binary. This eliminates the need to review large diffs which may include generated JavaScript code.

Adding Yourself to the Community Contributors List

If this is your first PR, please add your GitHub username/URL to the "Community Contributors" list here. Be sure to maintain alphabetical order.

If you open an Issue and a fix or update is made, you can open a subsequent PR adding yourself to the list and referencing the relevant issue.

Why Maintain a Contributors List?

  1. Every change counts. No matter how small, the cumulative effect is significant!

  2. In a traditional book publishing process, proofreading is a paid, full-time job. Listing contributors is a simple way to recognize effort for the same task.

Building and Reading the Book Locally

Setup mdbook (assumes you've already installed Rust per these instructions):

cargo install mdbook

If you're on Linux, you can leverage the Makefile provided in this repo. The supported make targets are below.

Render book (start webserver listening on http://localhost:3000, open book in default browser):

make read

Check progress (run checks and perform a page count):

make check

Clean (remove any artifacts generated by the above commands):

make clean

License

All text in this book, including any text contributions, is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) license.

All code in this book, including any code contributions, is licensed under the MIT License.

An Aside on Writing

If you're ever considering writing your own content, we say go for it! Blog posts are a great way to start, and you can always rework the contents into a book if appropriate. We believe that:

  1. Writing can help you refine ideas and deepen understanding, even if you never make it public.

  2. No matter what level you're at, there's always someone out there that's looking to reach your level and could benefit from your experience.

Static site generators like zola and mdbook make it easier than ever to get up and running. GitHub pages makes hosting hassle-free (supports custom domains and rotates SSL certs for you). No time like the present :)