Maintainer's Workflow

Preparations

1. Read and follow Testing Locally!

   This includes the setup of Ruby and the ability to build and inspect the website locally!

2. Add the pull request Git refs to your local Git clone.

   In your local copy of the website (e.g. in $HOME/projects/jlesc.github.io), as you have set up according to Basic Setup, edit .git/config and find the section for the upstream repository and adjust it to match the following:

    [remote "upstream"]
      url = [email protected]:JLESC/jlesc.github.io
      fetch = +refs/pull/*:refs/remotes/upstream/pr/*
      fetch = +refs/heads/*:refs/remotes/upstream/*
   

   The important part is the first fetch-line. This allows you to checkout the changeset of a pull request locally without adding the source repository of the PR, i.e. the contributor's fork, as a remote.

3. (optional but handy)
   Alias git fetch to git fetch --all --prune, at least for this repository.

4. (optional but strongly recommended)
   Make sure your GPG keys are working with Git for GPG-signed commits.

   That way we can always make sure the sources of the JLESC website are genuine.

A New Pull Request is Created

Whenever some contributor creates and opens a pull request (PR), you - the maintainer of jlesc.github.io - is asked for action! *hurray* We advice you to follow these steps closely to avoid future issues.

0. Check, whether the contributor has followed the advised steps in "Contributor's Workflow" including the naming of branches.

1. Wait for Travis to build and test the PR!

   You will see some basic information alongside the PR whether the build is currently running (orange dot), has successfully finished (green checkmark) or failed (red cross).

2. Inspect the Build

   1. orange dot
      Wait and keep reloading every few minutes.

      In general, it should not take Travis more than two to three minutes to complete the build.

   2. red cross
      Inspect the build log for errors!

      On the PR's page you will find a link to Travis' output for further inspection.

      Once you identified the error, comment on the PR and ask the contributor for a fix and stay tuned to help him/her out.

   3. green checkmark
      Inspect the build log for suspicious output!

      Never trust your contributors!

We now assume, the build has succeeded!

❗ Before merging the PR, you should inspect and test it locally ❗

3. On your computer

   1. Update all refs (see also point 2 of the preparations):

        git fetch --all --prune
      

   2. Checkout the source branch:

        git checkout source
      

   3. Make sure nothing lays around:

        git status
      

      Should tell you everything is clean.

   4. Update the source branch:

        git pull
      

   5. Try-merge the PR:

        git merge --no-commit --no-ff --log upstream/pr/<PR_NUMBER>/head
      

      The PR_NUMBER is the issue number of the pull request as displayed by GitHub.

      This will merge the full changeset of the PR into your local source branch without committing it. Thus, you will be able to inspect the changes and potentially fix some minor issues not worth bothering the contributor with, e.g. minor whitespace mistakes in _bibliography/jlesc.bib.

   6. Inspect the changelog and diff of all commits in the PR for any wanky lines!

      Minor typos or whitespace inconsistencies you should fix yourself. Bigger issues you should report back to the contributor by commenting on the PR.

   7. Build, run and test the site locally:

        bundle exec jekyll serve --watch --incremental --trace
      

      Open your browser at http://127.0.0.1:4000/.

   8. Assuming everything's fine, now either commit the merge locally and push it to GitHub:

        git commit --signoff -S
        git push
      

      ❗ In case the PR isn't fine yet, ABORT THE MERGE

        git merge --abort
      

      and contact the contributor or leave him/her a comment within the PR.