Skip to content

Latest commit

 

History

History
120 lines (79 loc) · 3.61 KB

CONTRIBUTING.rst

File metadata and controls

120 lines (79 loc) · 3.61 KB

How to contribute to this book [WIP]

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

If you ever need assistance with the process of getting your work written and included in this book, please reach out through your favorite medium listed at :doc:`/appendices/community-resources`.

We use GitHub to manage our workflow. If you plan on editing, authoring, or translating, please sign up there if you haven't already.

Sending feedback

You don't need GitHub to provide feedback, requests, suggestions, or other comments. You can post to the WarmPlace forum thread for this book, or discuss it using one of the chat platforms listed in :doc:`/appendices/community-resources`.

If you do use GitHub, you can also send feedback by filing an issue at https://github.com/metrasynth/sunvox-guide/issues.

Authoring and editing

We recommend that you set up a local environment for authoring and editing. This book makes extensive use of figures and audio samples, which are generated by a documentation builder.

Bug reports for documentation builder

When reporting a bug please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Setting up the documentation builder

  1. Fork sunvox-guide (look for the "Fork" button).

  2. Clone your fork locally:

    git clone [email protected]:your_name_here/sunvox-guide
cd sunvox-guide

  3. Perform one-time setup of third-party packages:

    pip install -r requirements.txt -r docs/requirements.txt

  1. Create a branch for local development:

    git checkout -b name-of-what-you-are-working-on

    Now you can make your changes locally.

  2. Run this command to build documentation:

    cd docs
make html

    Run this command to automatically rebuild documentation every time you make changes:

    cd docs
watchmedo shell-command -c "make html" -p '*.rst' -i '_build/*' -w -W -R .

    If you need to rebuild all pages, run this:

    cd docs
rm -rf _build/doctrees

  3. Open the sunvox-guide/docs/_build/html/index.html file in your web browser to review the changes.

  4. Commit your changes and push your branch to GitHub:

    git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-what-you-are-working-on

  5. Submit a pull request through the GitHub website.

Pull Request Guidelines

When you begin authoring a new section, or making a large change, please show others you are working on that section by doing the following:

  1. In your branch, change the top-level heading to indicate [WIP] at the end.
  2. Commit and push that change to GitHub.
  3. Open a pull request for the branch.

This will allow immediate discussion as the author needs it, as well as helping avoid duplicated work.

Once you are finished, another editor will assist with proofreading and will merge the results into the official repository.

Before merging, you should:

  1. Ensure all added or changed files render without errors.
  2. Add yourself to AUTHORS.rst.