Contributor's Workflow

This assumes, you have read and followed Basic Setup.

Update Your Local Copy

Before you start editing, you should, by all means, always update your local copy to contain all changes to the website added since you worked on your local copy the last time, i.e. pull the source branch from upstream.

We assume, your are in the working directory of your local copy of the JLESC website (e.g. in $HOME/projects/jlesc.github.io), as you've set up in Step 2 ff. of Basic Setup

1. Checkout the source branch:

    git checkout source
   

   In case this command fails, you have unstashed changes laying around, which you should either stash (git stash) or drop completely (git reset --hard, be careful with this command!).

   If you do not see folders like e.g. _assets, _bibliography, _includes, etc. (with a preceding underscore) you are probably on the master branch!

2. Get all upstream changes:

    git fetch --all --prune
    git pull
   

   This fetches all changesets from the upstream JLESC website repository to your local copy and updates your checked out source branch to the latest upstream state.

Starting Contributions

Here we describe the recommended workflow of adding your changes to your fork and getting them into the upstream repository and finally onto the official website.

We strongly encourage everybody to follow this workflow closely!

Never ever work and commit on the source branch directly
This will mess things up.

From now on, it is assumed you are in your local copy (e.g. in $HOME/projects/jlesc.github.io) and it is up to date according to the procedure above.

1. Create a feature branch to contain your changes.
   Chose a descriptive but short name, e.g. feature/my-latest-paper, feature/project-awesome or fix/bibtex-typos:

    git checkout -b feature/my-latest-paper
   

2. Add new content or fix existing.

   1. Read Basic Editing Knowledge to make yourself familiar with Markdown and the Liquid template language used throughout this project.

   2. Read Editing Pages for editing a project, software, event or news post.

   3. Read Editing Data to know about data available site-wide, such as people.

   4. Read Editing Publications to add a new or missing publication.

3. Add your changes to Git and commit them as you go:

    git add -A
    git commit --signoff
   

   A text editor (defaults to $EDITOR) will open querying you to enter a short but descriptive commit message (read this link!).

4. (optional)
   Read Testing Locally to see how you can view and test the website including your changes locally on your computer.

5. When you are done, push your branch with your changes to your fork on GitHub:

    git push -u my_fork feature/my-latest-paper
   

   The -u flag will tell Git that the remote tracking branch of the local feature/my-last-paper branch is in the my_fork remote repository. That way, you do not have to type it out each time you update this branch. A simple git push while being on that branch locally will do.

6. Go to the official JLESC website repository while being logged into GitHub.
   A notification should be displayed offering you to open a pull request (PR) from the branch you just pushed onto the source branch.

   

   In case no such notification pops up, you can create a pull request manually:

   1. Go to your fork on GitHub.

   2. Select your newly pushed branch, e.g. feature/my-latest-paper

   3. Click 'New pull request'

   4. Double-check that the base fork (the one mentioned first) is JLESC/jlesc.github.io, the base is source while the head fork is your fork and compare is your feature branch you want to being merged.

   5. Review the changes and formulate a descriptive pull request subject and message.
      GitHub will pre-fill it with a commit message.

   6. Open the Pull Request by clicking on 'Create pull request'.

7. Wait for one of the admins to merge your PR and see your content online.

   Meanwhile, Travis will try to build the website containing your changes to ensure your changes did not break anything important.

   Also, make sure the PR on GitHub is "green" as shown in the following screenshot:

   

   In case your PR branch needs an update, GitHub will tell you by offering a notification and button to do so:

   

   Just click on 'Update branch' and the admins will be able to merge your PR.

   Please, respond and follow any comments and remarks the admins do on your pull request.

8. Thank you very much for your contribution! 👍