CONTRIBUTING.md 3.32 KB
Newer Older
Marius Trautrims's avatar
Marius Trautrims committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
# 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].

Curtis Adam's avatar
Curtis Adam committed
16 17 18 19
* [build-section](https://git.thm.de/arsnova/cards/builds)
* [commit-message](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
* [merge-request](https://git.thm.de/arsnova/cards/merge_requests/new)
* [new-issue](https://git.thm.de/arsnova/cards/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=)
Marius Trautrims's avatar
Marius Trautrims committed
20 21 22 23 24 25 26 27 28

## 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
[You can use following tutorial to test your code style with Webstorm](https://git.thm.de/arsnova/cards/wikis/testing-with-webstorm)
Curtis Adam's avatar
Curtis Adam committed
32

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
### Automated User Acceptance Tests with chimp
Curtis Adam's avatar
Curtis Adam committed
43
We use chimp to automatically test the Front End functionality of [thm.cards](https://thm.cards). `Merge Requests will be only accepted if all chimp tests have been passed`.
Kevin Stroeher's avatar
Kevin Stroeher committed
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).
Kevin Stroeher's avatar
Kevin Stroeher committed
46

Marius Trautrims's avatar
Marius Trautrims committed
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
### 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
Curtis Adam's avatar
Curtis Adam committed
81
the [Wiki-Page](https://git.thm.de/arsnova/cards/wikis/code-documentation-with-jsdoc).
Lars Becker's avatar
Lars Becker committed
82

Marius Trautrims's avatar
Marius Trautrims committed
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,
Marius Trautrims's avatar
Marius Trautrims committed
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!