Skip to content

Home

Jump to bottom Edit New page
Thibaut Lunet edited this page Mar 25, 2022 · 49 revisions

NEW: Online editing

If you want to update an already existing page, you do not need to follow the standard Github procedure. Instead, simply browse the code online to find the file you want to edit and click on Edit this file (pencil in the upper right corner of the file viewer). Please select Create a new branch for this commit and start a pull request. when you are done and do not try to push to source directly.

Find out more here: https://help.github.com/articles/editing-files-in-your-repository. Dead simple, no more pull, branch, edit, add, commit, etc. Note that your changes will still be reviewed by a moderator, though.

This applies only if the file (e.g. the references) already exists. Otherwise, proceed with the guides provided here/below.

Contributing to parallel-in-time.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]/parallel-in-time.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 method named Awesome Method. You follow steps 1 to 5 as described above with feature/method-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/parallel-in-time.github.io.git. If successful, you should see something that looks like

    Cloning into 'parallel-in-time.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/method-awesome. This creates a new branch named feature/method-awesome and switches to it. You should see a message

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

  3. Now make your changes.

    For example, to create a new entry for your method, copy the method template from _templates/method_page to _methods/awesome-method.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@pintorg

    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 Method Awesome (or whatever you wrote as title in the markdown file) should appear under Methods.

    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 "[methods] Method Awesome added

    You should see something like

    [feature/method-awesome ae27ce3] [methods] Method Awesome added
1 file changed, 14 insertions(+)
create mode 100644 _methods/method-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/method-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/method-awesome -> feature/method-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. 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. ✨

    Thanks for contributing! ♥️

Where to Add Content

With the exception of a few files, all content is written with Markdown syntax and a couple of Liquid Tags. For a list of supported tags see Supported Liquid Tags.

The site is ordered into a few general topics: Events, Groups, Projects, Codes and News.

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

Topic Directory Template
Codes _codes code_page
Events _events_past event_past_page
_events_upcoming event_upcoming_page
Groups _groups group_page
Methods _methods method_page
News _posts news_post
Projects _projects project_page

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

Required Naming Conventions

There are some expected conventions for file names enforced by the conversion and build system (in our case Jekyll and Octopress).

Events (past and upcoming) and News

They 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.markdown
2014-05-26-3rd-pnt-workshop.markdown

And these are invalid file names:

07-2-1_tried-but failed.markdown
2014-05-26_3rd-pint-workshopt.markdown

Structure of Content Files

All content files (those, which are of type text/plain and have the .md ending) have a YAML-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, Template, Categories, etc.

The actual Markdown-formatted content follows after the header.

Testing the Site Locally

See Testing Locally.

Add a custom footer
Add a custom sidebar
Clone this wiki locally