Contributing to SARP Lessons

Contributing to SARP Lessons#

How can I contribute?#

Want to help make the SARP programming website better? Here are a few ways:

  • submit a Github Issue documenting a mistake or error you found on the website

  • contribute a piece of your code to the Examples section

Talk to your coding mentor to learn more about the steps for completing either of these contributions!

Set up the docs environment locally#

This repo can be cloned from github using the clone url:

git clone https://github.com/rwegener2/sarp_lessons.git

This copies the files from Github to your local computer.

To build this website you’ll need an environment seperate from the environment used by the students. You’ll need additional libraries only necessary for development, such as Jupyter Book, which automatically complies jupyter notebooks into nicely formatted web pages.

To install an environment with the required developer dependencies run the following from the root folder:

conda env create -f developer_env.yml

This will create an environment called sarp_docs for building and updating the website. It can be activated with conda activate sarp_docs. If working in Cryocloud jupyter-book is already installed in the base environment, so all the development code can be run by installing ghp-import with conda install ghp-import.

(Also, if you’re not using mamba yet, check it out! It’s a great package that really speeds up conda commands.)

Build the documentation#

Once you have an environment created you can build the docs. This website is setup as a series of Jupyter notebooks, which Jupyter Book complies into HTML. After making changes to the Jupyter notebooks you need to re-compile the HTML to create updated website source code.

To build the website HTML run (from the environment with jupyter-book installed):

jupyter-book build .

If running this on the cloud make sure you are using an instance with 3.7GB of memory or more.

After the jupyter-build command has completed a new folder should appear in the root, _build, which contains the website HTML files. You can view these files in the browser by running (also from the project root):

python -m http.server --directory _build/html/

This starts a local server by default on port 8000. Go to the browser, type localhost:8000 into the url box, and the locally compiled website should appear.

If you are working on a cloud platform you will need to use jupyter-server-proxy to access server ports. From your platform (with jupyter-server-proxy installed) view the website build by opening the following url in a new tab: hub.cryointhecloud.com/user/YOUR_USERNAME/proxy/8000/.

Development process#

You only need to build the environment once, but when making changes to the website you may go through the build process multpile times. A typical cycle after creating the development environment would be:

  1. Change the juptyerbook/markdown files with your content

  2. Build the HTML

  3. Open the server to view the compiled changes

  4. Repeat until you’re happy with how the new website looks

Once this cycle is complete you are ready to commit your changes.

Commit changes to Github#

Once a new change is made to the repository it can be added to Github. In good development practice, new changes should be make on a branch. Create a new branch with:

git checkout -b BRANCH_NAME

Good branch names are short but provide a hint of the change (ex. contrib_guide, netcdf_lesson, formatting_updates).

Integrating your changes into the repository involves commiting them. A nice dive into what the commit command is can be found here. The steps to commiting are:

  1. See what files have been changed with git status.

git status shows all the files that have been changed in the course of your work. These are the options availble for adding (next step).

  1. Add each of the relevant files with git add FILENAME.

git add FILENAME adds the files to a Staging Area, meaning they are queued up and ready to be commited.

  1. Make the final commit with git commit -m "COMMIT MESSAGE"

This takes your changes and officially logs them as part of your local repository. The git message will appear on Github as note to other developers what the change did. Examples include “add additional section for HDF files”, “update tabular data practice problems” or “fix errors in geospatial data lesson”.

Now the changes are in your local website repository, but they aren’t yet available on the remote repository. No one else other than you can see them. To move your changes from the local repository to the remote one where it will be publically available we push.

git push origin BRANCH_NAME

At this point you may be prompted to enter your Github username and password. If it is your first time pushing to this branch you may also be prompted to add the --set-upstream option. Once the push is successful you should see your branch and the changes on the public repo!: rwegener2/sarp_lessons.

Pull Request#

You can commit and push many times in the development process. Your changes will all stay on your own branch, so they won’t be reflected in the main source code. To integrate your changes into main you create a pull request from the branch you created (ex. my-new-feature) into main. I typically do this step in the browser. This guide walks through those steps.

Autodeployment#

The website is auto-deployed using Github pages. Github pages uses a Github Action to build HTML from the Juptyer notebooks and deploy it to the public url. While I believe this can be configured to happen on merge to the repo, right now the deploy command needs to be run manually.

Once the PR has been approved and merged into main the steps to deploy are:

  1. Checkout / pull the new main branch

  2. Run jupyter-book build .

  3. From the repo root run ghp-import -n -p -f _build/html

Running ghp-import updates https://nasa-sarp.github.io/sarp_lessons to show the HTML from the most recent build of main. It does this by pushing the content from _build/html to the ghp-pages branch of the repo which has been configured to deploy the HTML. There is no build process on the Github side (the developer is performing the build when they run jupyter-book build .. While there are more automated ways to do this, for now we can discuss who will deploy the changes in the PR comments. It can be anyone, not just the person who created the changes.