Skip to content

Home

Jump to bottom Edit New page
Daniel Ruprecht edited this page Jul 2, 2015 · 49 revisions

Contributing to parallel-in-time.github.io

Providing your own content: General workflow

If you don't have one yet, create a GitHub account. 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 entry looks like 'Clone this wiki locally' on the right.
  3. Checkout the source branch.
    ❗ Note: You never directly modify the master branch. It is created automatically from the source branch.
  4. Create a feature branch my-awesome-new-content or fix-annoying-typo
  5. Add new content, fix existing or add missing publications.
    1. Read Creating New 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. You fork the repository using the button on Github as described above and you prepare your local compute 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_git_username/parallel-in-time.github.io.git or https://github.com/your_git_username/parallel-in-time.github.io.git depending on whether you use SSH or HTTPS to clone. 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 add_method_awesome. This creates a new branch named add_method_awesome and switches to it. You should see a message
    Switched to a new branch 'add_method_awesome'.
  3. Now make your changes. For example, to create a new entry for your method, go into the subdirectory _methods, copy an existing entry, e.g. by typing cp parareal.markdown awesome.markdown and edit it.
  4. In order to see and test your changes, type rvm use 2.1.5@pintorg and then jekyll serve --watch in the root directory of your cloned repository. This will only work if you followed the steps under Testing locally, however. 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 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 - 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 filename. For example, assume you created a file awesome.markdown in the _methods directory, type git add _methods/awesome.markdown. Note: In Git, you will have to stage modified files before every commit (in contrast to SVN) or use the -a flag when committing.
  7. After adding some changes, you can commit using git commit -m "some useful message". You should see something like
    [test ae27ce3] some useful message 1 file changed, 14 insertions(+) create mode 100644 _methods/awesome.markdown
    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 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] add_method_awesome -> add_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 New 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.
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 .markdown 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.

Dear Future Maintainer

In case our Jenkins Server building and deploying the site currently, has reached the digital nirvana, look at Deploying The Site for instructions to deploy updates manually.

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