Updating the Website

From All Hands Active Wiki
Jump to navigation Jump to search

We use GitHub Pages to host our website. It is populated from the content checked into our Github site repo here: https://github.com/allhandsactive/site (which populates https://allhandsactive.github.io/site/ and https://allhandsactive.org). There is also a testing site located here: https://github.com/allhandsactive/site-test (populates https://allhandsactive.github.io/site-test/).

Generally, you will be making changes in the testing site only by using the set of instructions here. Once your changes are looking good on the testing site, let James K. or Nate Y. know want to push them to production, and they will work with you to bring those changes over. However, in the remote case that they are tragically clobbered by a falling pressure tank from a faulty SpaceX de-orbit, you will need to follow both sets of instructions, in order, to get your changes from testing into production.

Testing changes locally

You will need ruby and jekyll installed to run the test site locally as described in the README.md.

After cloning the repository, run bundle install to install any missing ruby gems. then run bundle exec jekyll serve to start the local server. You can then navigate to localhost:4000.

Making changes to the testing site

You have two ways to make changes to the testing site: the GitHub-based way (great for small changes; very quick to start with since it requires no repo setup, instead utilizing the built-in GitHub rich text editor), or you can use the Git-based way (for more advanced users; allows for bulk code changes, code refactoring, or other impressive Git wizardry, especially if you happen to really like your own rich text editor).


  1. Edit files as needed in the GitHub interface.
  2. You can check the changes to see how they look over on the testing site at https://allhandsactive.github.io/site-test/ .


  1. Clone the testing repo:
  2. Make whatever changes you are wanting to in this repo. You can use a branch if you wish, but we don't have a PR process for testing, and will ultimately be cherry-picking changes to bring over the production. If you can avoid generating a ton of commits to accomplish your work, this process will ultimately be much easier. :)
  3. When you are done making changes and want to see how the changes look, commit and push the changes into the testing repo using git add, git commit, etc.. If you aren't using a branch, you can push directly to master with:
    • git push origin master
  4. You can check the changes to see how they look over on the testing site at https://allhandsactive.github.io/site-test/ .

Promoting changes from testing to production

  1. Clone the production repo. We won't be making changes directly in here, but will add the testing repo under it:
  2. While in the production repo's directory, add the testing repo with the following command:
  3. Now fetch the branch from the testing repo:
    • git fetch test
  4. Switch to the testing repo's master branch:
    • git checkout test/master
  5. Verify you are in the correct spot by checking the logs with git log.
  6. Make a record of changes that need to come over based on your commit hashes in the log.
  7. Once you've got the list of your changes, switch back to the production master:
    • git checkout origin/master
  8. Make a new branch for cherry-picking the changes from testing over to production, e.g.:
    • git checkout -b enhancement/<some-clever-branch-name>
  9. Cherry-pick the hashes of the changes you are bringing over from testing. IMPORTANT: make sure you are cherry-picking in the order of OLDEST to NEWEST change, so you will likely have to go from bottom to top of the list you created previously. Do this on each hash by running:
    • git cherry-pick <hash>
  10. Resolve any merge conflicts you find along the way e.g. with "git mergetool". Once you have finished, push the changes into a new branch on the production repo:
    • git push origin enhancement/<some-clever-branch-name>
  11. Now create a new PR on the pushed branch, assign a reviewer, and add a description to reflect your PR's goal:
    • Check on your changes here https://github.com/allhandsactive/<project>/branches
    • Click on the Make a new Pull Request button
    • Assign a reviewer using the right-hand bar (normally artlogic or l0gik; or whoever else has agreed to work with you on website stuff. Preferably not just yourself, since it's good to have other eyes on the changes, and folks who know this process well).
    • Fill in some details about your change. Useful info would include if it is supposed to fix a specific issue (e.g. "Proposed fix for #<issue_number>").
    • Submit the PR for approval by the assigned reviewer.
    • Once the PR has been reviewed and approved, you can verify it made it through in the commit history, test it, etc..
  12. Once the PR is approved, the site will rebuild, and the changes should be live soon after.