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 Community resources [WIP].

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 Community resources [WIP].

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 git@github.com: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.