PSI work with GitHub

#PSI work with GitHub

Contributions can be made in several different ways. If you read through the specification documents, schema documentations or other files and feel that there is something unclear, wrong or just simply off, you can file an issue. If you feel there is something missing, you are welcome to make a suggestion. And of course you can also start working on implementing the suggestions and solve issues by a [developer contribution](Developer contributions).

##Issues If you feel that there is something missing, you can file an issue. (See https://guides.github.com/features/issues/, https://github.com/blog/1866-the-new-github-issues.) Give it a short but unambiguous title and a concise description. That way, it will also be readily locatable via the GitHub search. You should also use the search to locate related issues you might want to reference or if you are about to file a duplicate issue. In the latter case you can see from the issue page how far the topic is covered and join the discussion. If you have successfully filed an issue, make sure to also tag it with the most appropriate tags.

##Suggestions If you have a suggestion rather than an issue, you may also use the issues mechanism of GitHub. We have special tags for suggestions. You will be more likely to get more supporters to your suggestion, if the description is rather thorough. You can also use markdown for the description and attach files (a picture is worth a 1000 words 😉).

##Developer contributions

The work within the PSI(-QC) can be formally described as working on either:

1. XML documents such as schemas or example instances of the schema,
2. Hierarchical ontologies (.obo files) containing the metric definitions and
3. Text documents describing detailed a schema specification or a single metric

Git has a nice way of dealing with text files, their version history and diffs to keep track of the development. Points 1. - 2. are best worked on with your favourite editor offline, but once pushed to your fork, you can profit from the diff views and discussions and issue referencing on GitHub. If you want to know more about useful GitHub features be pointed to https://github.com/blog/821-mention-somebody-they-re-notified , https://guides.github.com/features/issues/ , https://github.com/blog/957-introducing-issue-mentions and of course the GitHub help.

If you are interested in our GitHub workflow, you can read about it on our wiki page about it.

Regarding point 3. , working on text or lists is of especially low threshold, as GitHub makes two things possible:

• work on text files directly from within the website (make sure it is your fork - exception: wiki)
• markdown files are rendered directly within the file view on the website. (This is especially true for the README.md files, which -if present- get rendered below the repository view in any folder of the repository structure.)

Markdown can be easily edited and formatted with a plethora of tools, not least with the GitHub built in editor. You have all basic and medium tools for formatting a text document as headers, text, lists, tables and embedding images. Markdown is easily converted to .pdf, .docx, etc..
Most importantly it allows content version control and GitHub rendering. Advice: write each sentence in a separate line so the development can be tracked on a sentence level. Paragraphs are represented as double new lines in markdown.