Contribution workflow

[cm-smith]

When we want to contribute (i.e., submit a PR) to this Github Pages repo, is it recommended to install Ruby (and dependencies) to test the Jekyll site locally?

This might be the only way to verify/debug the proposed edits? Alternatively, folks could confirm the Markdown view renders properly (when clicking on the *.md file in Github), but this won't guarantee success if there are changes to the site config (YAML).

Thanks!

[anthonylollo]

Yeah open to suggestions. I wasn't able to get the site working locally and did a bit of debugging in the beginning to get it to work, but would be very nice to be able to test before pushing to avoid tons of additional commits.

[cm-smith]

Looks like if we're trying to avoid local builds, then the recommendation is Git-oriented. Commit changes to Github, temporarily change the Github Pages settings to compile from the dev branch, then confirm updates.

To your point, that could end up with a lot of commits if we don't rebase or squash whenever there's faulty code committed. I don't think that's a huge deal, though, since our dev workflows don't typically require scouring the git history.

[anthonylollo]

One option that seems simpler would be the following.

pip3 install mkdocs cd to the project directory python3 -m mkdocs serve

and then the site can be opened locally and proofread/checked for anything that isn't rendering properly