How to contribute to this book

Submitting suggestions

Have a suggestion for improvement? Share it by opening an issue

Authoring content

Setup authoring environment

  1. Install Sphinx locally:

    $ pip3 install sphinx

    This can be in your home area, a virtual environment, container, etc.

  2. Download a copy of the book source:

    $ git clone https://code.ornl.gov/99R/olcf-cookbook

  3. Build the book:

    $ cd olcf-cookbook && make html

  4. Locally preview the generated web pages

    Point your web browser to file:///<path to pwd>/_build/index.html

Edit the book

  1. Setup your environment as above

  2. Create a new branch to make your edits:

    $ git checkout -b my-edits-branch

  3. Re-build and preview your edits:

    $ make html

  4. Commit your edits:

    $ git commit -am "Describe your changes here."

  5. Create a patchfile showing changes since the develop branch:

    $ git format-patch develop

  6. Email the authors directly and attach your patches.

GitHub Guidelines

Here are some guidelines and common practices that we use in this project.

  • When you want to work on an issue, assign it to yourself if no one is assigned yet. If there is somebody assigned, check in with that person about collaborating.
  • Reference the issue(s) that your PR addresses with GitHub’s ‘#’ notation.
  • Use “WIP” in your PR title to indicate that it should not be merged yet. Remove just the WIP when you are ready for it to be merged.
  • You do not need to assign labels to your PR, but you may do so if you have suggestions. However, be aware that the labels might get changed.