CONTRIBUTING.md 3.32 KB
Newer Older
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=)
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`.
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
### 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

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!