CONTRIBUTING.md 3.35 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
# Contributing

ARSnova Flashcards needs you! If you are interested in helping, here is a short guide.

## Step-by-step summary

1. First, fork and clone our repository.
2. Create a topic branch.
3. Make your changes. Be sure to provide clean commits and to write [expressive commit messages][commit-message].
4. Stay up to date with our repository: Rebase to our `staging` branch using `git rebase`.
5. Push the changes to your topic branch.
6. Finally, [submit a merge request][merge-request].

If you don't feel like writing code, you could also update the documentation. And if you find any bugs, feel free to [open a new issue][new-issue].

[build-section]: https://git.thm.de/arsnova/flashcards/builds
[commit-message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[merge-request]: https://git.thm.de/arsnova/flashcards/merge_requests/new
[new-issue]: https://git.thm.de/arsnova/flashcards/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=

## How we review merge requests

To get your merge request accepted faster, you should follow our review process before submitting your request. Here is our list of dos and don'ts.

### No merge conflicts

This is a no-brainer. Keep your branches up to date so that merges will never end up conflicting. Always test-merge your branches before submitting your pull requests. Ideally, your branches are fast-forwardable, but this is not a requirement.

29 30
### Code Style

Curtis Adam's avatar
Curtis Adam committed
31 32
[You can use following tutorial to test your code style with Webstorm](https://git.thm.de/arsnova/flashcards/wikis/testing-with-webstorm)

33 34 35 36 37 38 39 40 41
This project makes use of both jscs and jshint. You can review your code with the defined rules by using gulp. Install:

```
npm install -g gulp
npm install
```

Then, you can either run the script one time with ```gulp --gulpfile .gulpfile.js``` or you can watch the directory with ```gulp watch --gulpfile .gulpfile.js```

Curtis Adam's avatar
Curtis Adam committed
42 43
### Automated User Acceptance Tests with chimp
We use chimp to automatically test the Front End functionality of [arsnova.cards](https://arsnova.cards). `Merge Requests will be only accepted if all chimp tests have been passed`.
44

Curtis Adam's avatar
Curtis Adam committed
45
For more information about user acceptance tests have a look at [tests/HOWTOTEST.md](tests/HOWTOTEST.md).
46

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
### Project structure

Since Meteor is supporting ES6 (ES2015) we use the import/export statements to modularize the application.
Please take a look at our project file structure for the clients:

```
client/
  head.html
  head.js
  head.scss
i18n/
imports/
  api/
  startup/
    client/
      i18n.js
      registerhelper.js
      routes.js
    server/
      accounts-config.js
      initialize.js
  ui/
public/
server/
  main.js
```

### Use UTF-8

Sadly, some editors still do not have UTF-8 as their default setting. Using the wrong encoding will destroy non-ASCII characters like french quotation marks or umlauts.

Lars Becker's avatar
Lars Becker committed
78 79 80 81 82
### Documenting your code

We use [JSDoc](https://github.com/jsdoc3/jsdoc) with the [DocStrap](https://github.com/docstrap/docstrap) template to document our code! For more information, you can visit
the [Wiki-Page](https://git.thm.de/arsnova/flashcards/wikis/code-documentation-with-jsdoc).

83 84 85 86 87 88
### Summary

It all comes down to

* reviewing your own changes,
* keeping your commits clean and focused,
Lars Becker's avatar
Lars Becker committed
89
* documenting your code,
90 91 92
* and always staying up to date.

If you keep these things in mind, your merge requests will be accepted much faster. Happy coding!