Skip to content

Latest commit

 

History

History
189 lines (133 loc) · 8.32 KB

CONTRIBUTING.md

File metadata and controls

189 lines (133 loc) · 8.32 KB
Raw

Contributing to the fmi-standard.org website

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and features.

Feature requests

Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible.

Pull requests

Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

If you only want to make small changes you can edit files and open pull requests directly from your browser. Please chose an expressive name for your branch like add-my-news-post (not patch-x).

If you plan bigger changes you can fork and clone the repository to your local machine.

Please ask first before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

Commit messages

Please follow the seven rules of a great Git commit message when committing your changes:

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why vs. how

For example:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If the commit it related to an issue, put references to them at the
bottom, like this:

Resolves: #123
See also: #456, #789

Updating the tools list

The tools page is the central location to find and get information about tools that support FMI. The page is generated from tools.csv. To add, edit or remove a tool from the list, update the respective line and make a pull request. To get green buttons the tool has to pass the FMI Cross-Check. Please respect the rules below when editing the file.

Format

Optional fields may be empty.

Column Description Example / valid values
name The tool name that appears in the tools list Example Sim
id Unique tool ID (must be a valid directory name) Example-Sim
homepage Link to the tool's homepage (optional) https://example.com/example-sim/
description A description of the tool Run simulations in the cloud in real time
license License (commercial or OSI approved) commercial, osi
platforms List of supported platforms, space separated 'c-code win32 win64 linux64'
export_cs_fmi1 FMI 1.0 Co-Simulation export (optional) planned, available
export_cs_fmi2 FMI 2.0 Co-Simulation export (optional) planned, available
export_me_fmi1 FMI 1.0 Model Exchange export (optional) planned, available
export_me_fmi2 FMI 2.0 Model Exchange export (optional) planned, available
import_cs_fmi1 FMI 1.0 Co-Simulation import (optional) planned, available
import_cs_fmi2 FMI 2.0 Co-Simulation import (optional) planned, available
import_me_fmi1 FMI 1.0 Model Exchange import (optional) planned, available
import_me_fmi2 FMI 2.0 Model Exchange import (optional) planned, available

Position in the table

The alphabetical order based on the tool name (case insensitive). Take a look at the ASCII table if in doubt.

Tool Description

The description field should

  • be a short description of the tool
  • not repeat information that is in the table (supported platforms, FMI types and versions, vendor and license)
  • have no dot (.) at the end if it's only one sentence
  • be neutral and not use biased additions like leading, innovative, flexible or buzzwords (performance, next generation)
  • not contain hyperlinks or markup

Adding a news post

To create a post, add a file to the _posts directory with the following format:

YEAR-MONTH-DAY-title.MARKUP

Where YEAR is a four-digit number, MONTH and DAY are both two-digit numbers, and MARKUP is the file extension representing the format used in the file. The date determines the placement in the news chronology and must not be in the future in order to be listed. title should not be longer than 50 characters and only contain lower case characters (a-z), digits (0-9) and hyphens (-).

The file name determines the permalink to the post and must not be changed after it has been merged into master. E.g. the post

2018-09-04-modelica-conference-2019-regensburg-germany.md

can be accessed as

https://fmi-standard.org/news/2018/09/04/modelica-conference-2019-regensburg-germany.html

You typically write posts in Markdown (.md), however HTML (.html) is also supported.

All blog post files must begin with a front matter that sets the title, category and layout:

---
title: FMI at the 13th Modelica Conference 2019 in Regensburg, Germany
categories: [news]
layout: post
---

The [13th International Modelica Conference](https://modelica.org/events/modelica2019) will be held at [OTH Regensburg](https://www.oth-regensburg.de/en.html), Germany, March 4–6, 2019.

The scope of the conference includes FMI in Modelica and non-Modelica applications and tools.

To include images, downloads or other files along with a post place them in the assets directory and reference them using the following markdown syntax:

... which is shown in the screenshot below:
![My helpful screenshot](/assets/screenshot.jpg)

Linking to a PDF for readers to download:

... you can [get the PDF](/assets/mydoc.pdf) directly.

Building the website locally

  1. Clone the repository, change into the directory and pull the changes

    git clone https://github.com/modelica/fmi-standard.org.git
cd fmi-standard.org
git pull

  2. Install Docker

  3. Build the site and make it available on a local server

    docker run --volume="$PWD:/srv/jekyll" -p 4000:4000 -it jekyll/jekyll jekyll serve

    Now browse to http://localhost:4000

  4. Before you push your changes, build and check your commit for syntax errors and broken links:

    docker run -v $PWD/_site:/site 18fgsa/html-proofer /site --only-4xx