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) 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.

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.

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!

3. On your computer

   1. Update all refs (make sure you have followed point 2 of the preparations:

        git fetch --all --prune
      

   2. Checkout and update the source branch:

        git checkout source
        git pull
      

   3. Try-merge the PR:

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

      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.

   4. 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 contribtor by commenting on the PR.

   5. Build, run and test the site locally:

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

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

   6. Commit or Abort

      Depending on the outcome of the previous point, you either commit merged the PR or abort the merge as the contributor has to fix some issues.

      1. Everything's fine

         1. Make sure the contributor is listed in the CONTRIBUTORS file.

            Also make sure, the .mailmap file for Git is up to date with respect to the contributor.

         2. Commit the merge:

              git commit --signoff -S
            

            Adjust the first line of the merge commit message to match the following pattern:

              merge PR #<PR_NUMBER> by @<CONTRIBUTOR'S_GITHUB_USERNAME>
            

         3. Push the source branch

             git push
            

      2. Contributor has to fix things and update the PR

         Abort the merge:

          git merge --abort
         

         This will reset your source branch.