Home

Contributing to jlesc.github.io

Getting Started - The General Workflow

If you don't have one yet, create a GitHub account. It's free and no hidden costs burried. In case you have never used GIT before, a brief explanation of the very basics can be found e.g. here. Or just use your favorite search engine, there are many and more tutorials for GIT out there.

1. If this is the first time you are contributing to the website: Fork the repository.

   If you already forked the repository before, you may want to sync your fork now (be sure to sync both your master and source branches).

2. Clone your fork.
   You can copy the link from your fork's GitHub page. The URL looks like [email protected]:[YOUR_USERNAME]/jlesc.github.io.git.

3. Checkout the source branch.
   ❗ Note: You never directly modify the master branch.
   It is created automatically from the source branch. If you do not see folders like e.g. _methods (with a preceding underline) you are probably in the master branch.

4. Create a feature branch feature/new-bibtex-refs or feature/typo-fix

5. Add new content, fix existing or add missing publications.

   1. Read Creating Pages or News.
      If you are not familiar with markdown, just look at existing entries: It is easy.

   2. Read Adding Publications.
      Adding a new or missing publication to the list is easy as adding a BibTeX entry to the BibTeX file.

6. Read Testing Locally to see how you can view the website locally on your computer.

7. Add and commit your changes, then push them to your forked repository on GitHub.

8. Create a pull request (PR) against the source branch

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

An example

Assume you want to add a new entry for your project named Awesome Project. You follow steps 1 to 5 as described above with feature/project-awesome as the branch name and you prepare your local computer by installing RVM and Ruby as described under Testing Locally. Then,

1. Clone your forked repository to your local machine by typing git clone URL where you can copy&paste the URL from the GitHub page of your fork. It should look like [email protected]:YOUR_USERNAME/jlesc.github.io.git. If successful, you should see something that looks like

   Cloning into 'jlesc.github.io'...  
   remote: Counting objects: 1631, done.  
   remote: Compressing objects: 100% (4/4), done.   
   remote: Total 1631 (delta 0), reused 0 (delta 0), pack-reused 1627  
   Receiving objects: 100% (1631/1631), 1.80 MiB | 1.32 MiB/s, done.    
   Resolving deltas: 100% (814/814), done.   
   Checking connectivity... done.
   

2. Create and checkout a new branch in which you will make your modifications: Type git checkout -b feature/project-awesome. This creates a new branch named feature/project-awesome and switches to it. You should see a message

   Switched to a new branch 'feature/project-awesome'
   

3. Now make your changes.

   For example, to create a new entry for your project, copy the project template from _templates/project_page to _projects/awesome-project.md. Make sure, the file ending is .md! Then edit the newly copied file.

4. (this assumes you have set up your computer according to Testing Locally)
   In order to see and test your changes, type

    rvm use 2.2.1@jlescorg
   

   and then

    bundle exec jekyll serve --watch
   

   in the root directory of your cloned repository. This will only work if you followed the steps under Testing locally! You will see some messages and, if your website is build successfully, something like

   Server address: http://127.0.0.1:4000/  
   Server running... press ctrl-c to stop.
   

5. Switch to your browser and type http://127.0.0.1:4000/ to see the website with your changes: In our example, a new entry called Project Awesome (or whatever you wrote as title in the markdown file) should appear under Projects.

   You can now continue you edit your markdown files in another terminal or your favourite editor - Jekyll will continually update the locally delivered website - or throw an error message if you write something in your markdown files that Jekyll can't understand (e.g. wrong syntax).

6. Add and commit your changes: To stage a new or modified file for commit, type

    git add -A
   

   Note: In Git, you will have to stage modified files before every commit (in contrast to SVN).

7. After adding some changes, you can commit using

    git commit -m "[projects] Project Awesome added
   

   You should see something like

[feature/project-awesome ae27ce3] [project] Project Awesome added 1 file changed, 14 insertions(+) create mode 100644 _projects/project-awesome.md

You don't have to put all your changes into a single commit - on the contrary, it can be useful
to commit many smaller changes.
Just keep committing until you are satisfied with your modifications and additions.

8. Now it is time to get your changes (i.e. your new branch with all your commits) from your local
machine to GitHub:
Type

     git push -u origin feature/project-awesome

to push your new branch to your forked repository.
You should see a message similar to the one you got when cloning plus a line like

• [new branch] feature/project-awesome -> feature/project-awesome

9. When you now visit your forked repository on GitHub, you should be able to see your just
committed branch and open a [pull request](https://help.github.com/articles/using-pull-requests/).
This will signal the administrators that you have some content you would like to add to the
website - we will check it and if it is okay, merge it (you should be notified by an email from 
GitHub once this happens).

After merging, your changes should be quickly visible on the website. :sparkles:

Thanks for contributing! :hearts:


### Where to Add Content

With the exception of a few files, all content is written with
[Markdown](http://daringfireball.net/projects/markdown/) syntax and a couple of
[Liquid Tags](jekyllrb.com/docs/templates/index.html).
For a list of supported tags see [[Supported Liquid Tags]].

The site is ordered into a few general topics: **Events**, **Projects** and **Software**.

Each of these topics has an own directory where to put new content and certain templates:

| Topic    | Directory                               | Template                 |
|----------|-----------------------------------------|--------------------------|
| Events   | [`_events_past`][events_past]           | `event_past_page`        |
|          | [`_events_upcoming`][events_upcoming]   | `event_upcoming_page`    |
| News     | [`_posts`][posts]                       | `news_post`              |
| Groups   | [`_groups`][groups]                     | `group_page`             |
| Software | [`_software`][software]                 | `software_page`          |
| Projects | [`_projects`][projects]                 | `project_page`           |

Read about the short and few details on [[Creating Pages or News]].

[events_past]: https://github.com/JLESC/jlesc.github.io/tree/source/_events_past
[events_upcoming]: https://github.com/JLESC/jlesc.github.io/tree/source/_events_upcoming
[posts]: https://github.com/JLESC/jlesc.github.io/tree/source/_posts
[groups]: https://github.com/JLESC/jlesc.github.io/tree/source/_groups
[software]: https://github.com/JLESC/jlesc.github.io/tree/source/_software
[projects]: https://github.com/JLESC/jlesc.github.io/tree/source/_projects


### Required Naming Conventions

There are some expected conventions for file names enforced by the conversion and build system
(in our case [Jekyll](http://jekyllrb.com/)).


#### Events (past and upcoming)

The file name must start with a date of the form `YYYY-MM-DD` followed by the title in lowercase
and simple dashes as word separation.
Please, use the event's starting date here.  
The follow are valid file names:

 2013-02-21-awesome-news.md
 2014-05-26-3rd-workshop.md

And these are **invalid** file names:

 07-2-1_tried-but failed.md
 2014-05-26_3rd-workshop.md


### Structure of Content Files

All content files (those, which are of type `text/plain` and have the `.md` ending) have a
[YAML](http://yaml.org/)-formatted header enclosed in two lines of three dashes.

This header provides all the basic meta information for the specific content, such as *Title*,
*Author*, *Creation Date*, *Date of Last Update*, *Rendering Template*, etc.

The actual Markdown-formatted content follows after the header.


### Testing the Site Locally

See [[Testing Locally]].