Skip to content

Latest commit

 

History

History
87 lines (55 loc) · 4.06 KB

CONTRIBUTING.md

File metadata and controls

87 lines (55 loc) · 4.06 KB

Contributing to the Spyderisk csv2doc Project

Welcome!

We'd love to have your contributions to the Spyderisk csv2doc project. This document is about our practical principles of working.

The overall Spyderisk aim is to

understand the trustworthiness of socio-technical systems by establishing an international Open Community supporting the research, development, use and support of open, effective, and accessible risk assessment methods, knowledge and tools.

and you can read more about this in the general Spyderisk description, which explains who we are and what we do.

Please read our Code of Conduct to keep our community approachable and respectful.

Who can contribute?

We need all the help we can get on the software and computing side of Spyderisk. In the csv2doc project it's mostly about python and web development, and understanding ontologies and domain model representations.

If developing this interests you, first read DEVELOPMENT.md for an overview of the internals. Also, do please drop an email to [email protected] or open a discussion issue on GitHub to share with us what you are up to.

In addition you might want to:

  • Look at our List of Open Issues you think you would like to solve, and add a comment to say that you are working on a fix, or
  • Create a new query or bug report as described in the following section, and make a fix for it
  • Follow the "How to submit a patch" procedure below

How to open a query or bug report

At this stage in our young open project, two things are true: there are many bugs to find, and, very often a problem is because the user does not understand how Spyderisk works. If its the latter, then you have not found a bug. When you have a problem, we recommend you:

  • Open a new issue in domain-csv2doc
  • Select the template marked "New Spyderisk query". If you are very sure its a bug, select "New Spyderisk bug report"

How to submit a patch

You are about to make us very happy. There are several cases:

  • Documentation fix - create a fork and send a pull request
  • Obvious code fix - create a fork and pull request, same as for documentation
  • Any other code fix - please create a query or bug report according to the previous section. It may well be that you have code which is good to go, but in our young open project there is a lot of context that might be relevant to what you wish to do.

But basically just talk to us using whatever means you are comfortable with, and we will figure it out.

Spyderisk project principles

Openness first

  • Our software licensing is Apache 2, and analogously for documentation
  • Our communication is collaborative and collective
  • We build our software around openly published academic theory

Version control is mandatory

  • Our software is under public version control.
  • Our models expressed in data dumps are also under version control
  • We create PURL permanent URLs for software and documentation when there are important new versions. PURL is maintained by archive.org which we hope is stable for the long term
  • We have some legacy software outside the system-modeller Git tree which cannot yet be versioned, but we are working hard on that

Transparency trumps accuracy

Spyderisk needs to be both trustable and also to progress quickly. Where there is incomplete or inaccurate work in the Spyderisk System Modeller code then we document this with the string:

WIP: BRIEF TEXT DESCRIPTION, https://github.com/Spyderisk/system-modeller/issues/NNN

Where "BRIEF TEXT DESCRIPTION" should not exceed a couple of sentences, and NNN should be the most relevant issue.

Communication with the Spyderisk community

  • tbd

Wiki and documentation

  • tbd