CONTRIBUTING.md

Contributing Guidelines

We believe in the power of open source development and want to encourage everyone to contribute to this project. This document should help new developers and documents our coding workflow. If there are any questions left, don't hesitate to open a new issue explaining that you haven't found the information in the docs.

Developer vibes

Please keep being friendly and don't troll. See our Code of Conduct for more information on this.

Issues

You have an idea about a new feature or you spotted a mistake? Feel free to create an issue in which you describe the problem / the feature requirements. Please try to find similar issues first though, and add your information there to keep it organized.

As soon as an issue is assigned to somebody, it means that this person is responsible for fixing it.

Local installation

1. Install npm
2. Clone the repository
3. Navigate into your clone's directory (probably open-fixture-library/)
4. Run npm install

Now, everything's installed and should be working. To start the website server at http://localhost:5000/, run npm run dev (see UI docs).

Where you can help

• Add new fixtures (either via the Fixture Editor or by manually writing a fixture format JSON)
• Browse the good-first-issues tag to find some easy tasks
• Improve the documentation
• Add new plugins (use existing ones as reference and look at the plugin documentation)
• Implement your own idea (please create a new issue first if it's no bugfix or very minor change)

Workflow: How to implement a feature

1. Fork the repository
2. Setup your local installation (see above) with your fork
3. Create a new branch for your feature
4. Do the needed changes, commit and push them
5. Create a pull request to merge your changes back into our project

You can also create the pull request if you're not done yet to involve the reviewers into the development process and get help if you're stuck. Please include WIP (work in progress) in the pull request title in this case.

Code style

We always aim to have clear, readable code. So please try to respect these principles:

• Document every new function with JSDoc
  • Primitive types are lowercase: number, string, boolean, array, object
  • Be careful with arrays: Prefer the array.<string> syntax over string[]
• Use self-describing variable names and prefer constant variables over literal values without explanation
• Prefer code readability over micro-optimisation
• Use new ES2015 (ES6) features that improve code readability, for example:
  • Instead of var, use const where possible, let in all other cases
  • Prefer Array iteration methods (like map(...), filter(...), some(...), every(...), find(...)) with arrow functions over loops
  • Always use template strings (backticks instead of single or double quotes: const str = `My name is ${name}.`;) as they are strictly better strings and make string concatenation (const str = 'My name is ' + name + '.';) more readable
• Try to make a piece of code not too complex. That is, if a function contains lots of ifs and for-loops, extract some parts into helper functions. (For example, the checkFixture() function calls checkPhysical() and checkChannels(), checkChannel() calls checkCapabilities(), etc.)

We automatically check code style using ESLint. Maybe your IDE supports ESLint highlighting (there's a good extension for VSCode) – this helps spotting bad code style as quickly as possible.

Developer tips

• To understand how OFL works, read the Documentation Overview and its related pages. We try to document every part of our software.
• Run tests in the tests/ directory manually – that's way faster than waiting for the automated Travis tests in pull requests.
• Run make to be sure that auto-generated contents are up-to-date.