Skip to content

Latest commit

 

History

History
129 lines (80 loc) · 5.1 KB

CONTRIBUTING.md

File metadata and controls

129 lines (80 loc) · 5.1 KB
Raw

Contribute

We love contributions! This analysis guide is open source, built on open source, and we'd love to have you help make it even better!

First off, if directly writing content in this repository is too unfamiliar and you just want to write what you know down, we will be happy to accept contributions in any form. Our preferences would be for something which is as close to markdown as you are comfortable writing, so if not markdown then plain text, LaTeX, or lightly formatted word documents are all ok (in that order of preference).

If you are happy to contribute directly to the source on GitHub then thank you! We have tried to make it as approachable as possible, but if you encounter any issues then please let us know.

Getting Started

The first step is to sign up / sign into GitHub.

The next step is to fork the repository to your own GitHub account, to do this go to https://github.com/DKISTDC/dkist-analysis-guide/fork.

Then, you clone the repository to your local machine. First make sure you have generated an SSH Key and added it to your GitHub account.

To clone the repository run:

$ git clone [email protected]:<your github username here>/dkist-analysis-guide.git

setting your github username as required.

Next we want to add the upstream DKISTDC repository to your local clone:

$ git remote add upstream [email protected]:DKISTDC/dkist-analysis-guide.git

Then we can update the remotes with:

$ git remote update

This should set you up with a local copy of the files to edit.

Creating a Python Environment

Using conda (recommended)

If you don't already have conda installed you can follow the instructions here for installing miniforge.

If you already have conda installed you need to create a new environment for the analysis guide and then install the requirements:

$ conda create -n dkist-analysis-guide -c conda-forge python unidep
$ conda activate dkist-analysis-guide
$ unidep install .

When coming back to work on the analysis guide make sure you run conda activate dkist-analysis-guide to activate the environment.

Using pip

If you are using pip, please create an isolated virtual environment and then run:

$ pip install 'unidep[all]'
$ unidep install --skip-conda .

Authoring Content

Building the guide

The easiest way to preview the guide as you are working on it is to run:

$ jupyter-book build analysis-guide

The end of this command should print a file path for you to open in your web browser.

Editing Files

The guide is written in a markup language called MyST which is an extension to markdown. Each chapter has it's own file which are built into a variety of possible output formats by jupyter book. The chapters of the book are defined in the _toc.yml file, more information about the structure of the guide can be found in the jupyter book documentation.

Adding Chapters

To start a new chaper, create a new markdown file (.md) and then add the filename to the _tox.yml file.

Style

When writing content in the markdown files, please write one sentence per line as this helps when using git.

Submitting your changes

Once you have edited the guide and want to submit your changes, you will need to make a Pull Request. To do you this you need to:

  • Locally commit your files to git.
  • Push these commits to your fork on GitHub.
  • Open a Pull Request.

The first step is to create a new local branch with git:

$ git switch -c <branch name>

replace <branch name> with a name for your branch such as "intro-improvements".

Then we will add and commit all the changes:

$ git add .
$ git commit -m "<some commit message>"

replace <some commit message> with a short descriptive message such as "fixed typos in intro page".

Next we need to push these changes to your fork on GitHub which we setup at the start of the guide:

$ git push origin <branch name> --set-upstream

again, replacing branch name with the name of the branch you used earlier. The output of this command should give you a shortcut link to open a pull request from this branch, but if not you can navigate to https://github.com/<your github user name here>/dkist-analysis-guide/pull/new/<branch name> replacing your GitHub username and branch name as needed. Type a descriptive title and a short description and then click "Create Pull Request". This will then run some automatic tests and notify people to review your contribution.