CONTRIBUTING.md 5.75 KB
Newer Older
1
# Contributing: Vadere
Felix Dietrich's avatar
Felix Dietrich committed
2

3 4 5 6
This guide explains the repository structure, how to set up the development environment and introduces coding guidelines.

## Repository Structure

Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
7
The repository contains following `files` and `folders`:
8 9

- The Vadere source code: divided into the sofware modules `VadereGui`, `VadereMeshing`, `VaderSimulator`, `VadereState`, `VadereUtils`
10
- `Scenarios`: pre-shipped tests for different purposes and different locomotion models (e.g., gradient navigation model, optimal steps model and the social force model)
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
- `Tools`: scripts which are executing during the continuous integration phase.
- `.gitlab`: templates for creating issues in the Vadere [issue tracker](https://gitlab.lrz.de/vadere/vadere/issues) (this files are implicitly used by GitLab).
- `.gitlab-ci.yml`: instructions which are executed during the [continuous integration pipeline](https://docs.gitlab.com/ee/ci/quick_start/).

## Development Setup

1. Follow the **installation instructions** in the [README.md](README.md) to install all required software and to get the source code.
2. Open a shell and `cd` into the project directory.
3. Run `mvn clean install`.

The project can now be imported *As Maven Project* into your IDE.

### Eclipse

1. *File* > *Import* > *Maven* > *Existing Maven Projects*
2. Choose `pom.xml` as *Root Directory* and click *Finish*
3. Open *Vaderegui (gui)* > *src* > *org.vadere.gui.projectview* > `Vadereapplication`

### IntelliJ IDEA

1. On the welcome-screen select *Import Project*
2. Select `pom.xml` > *Next* > *Next* > *Next* > *Finish*
3. Open *VadereGui (gui)* > *src* > *org.vadere.gui.projectview* > `VadereApplication`
4. lick the *run*-icon next to the `main` method
5. Edit the run configuration for `VadereApplication` to build the project using Maven instead of IntelliJ's internal builder to avoid compilation errors:
6. Click *Edit Configurations* (in dropdown menu next to the play/debug button)
Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
37
7. Under *Before launch*, **remove all existing** build instructions and add *Run Maven Goal* and use the Maven goal `compile`
38 39 40 41

Alternatively, run `mvn eclipse:eclipse` using the [Maven Eclipse Plugin](http://maven.apache.org/plugins/maven-eclipse-plugin/usage.html) or `mvn idea:idea` using the [Maven IntelliJ Plugin](http://maven.apache.org/plugins/maven-idea-plugin/).

## Workflow
42 43 44 45

To efficiently contribute to this project, you need an LRZ GitLab account.
Please contact us and we will send you an invitation.

46 47
### Use the Issue Tracker

Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
48
Please, use the [issue tracker](https://gitlab.lrz.de/vadere/vadere/issues?sort=label_priority) for both
49 50

- to request a feature or to report a bug (see [how to write new issues](https://gitlab.lrz.de/vadere/vadere/issues/179))
Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
51 52
- to work on a feature (see [how to work on an issue](https://gitlab.lrz.de/vadere/vadere/issues/184))

Benedikt Kleinmeier's avatar
Benedikt Kleinmeier committed
53
**Tip:** Sort the issues in the [issue tracker](https://gitlab.lrz.de/vadere/vadere/issues?sort=label_priority) by `Label priority`.
54 55 56 57 58 59 60 61 62

### Steps for External Contributors

The workflow is the following:

1. **Fork this Git repository**
2. Clone your own fork to your computer
3. Checkout a new branch and work on your new feature or bugfix
4. Push your branch and **send us a merge request**
63 64 65 66 67

These steps are explained in more detail at the
[GitHub help pages](https://help.github.com/articles/fork-a-repo/).
Merge/pull requests are described [on GitLab](https://about.gitlab.com/2014/09/29/gitlab-flow/#mergepull-requests-with-gitlab-flow).

68 69 70
## Style Guides

### For Coding
Felix Dietrich's avatar
Felix Dietrich committed
71 72 73

Basic rules:

74 75 76 77 78 79
- No warnings
- No unused imports
- No unecessary `this.` qualifiers
- Use the formatting tool!
  - Eclipse: select text (optional) and press <kbd>ctrl</kbd> + <kbd>shift</kbd> + <kbd>f</kbd>
  - IntelliJ: select text (optional) and <kbd>ctrl</kbd> + <kbd>alt</kbd> + <kbd>l</kbd>
Felix Dietrich's avatar
Felix Dietrich committed
80 81 82

For source code formatting, we use an adapted version of
[Google's Coding style guide](https://google.github.io/styleguide/javaguide.html).
Jakob Schöttl's avatar
Jakob Schöttl committed
83
Please check the [README in this repository](https://gitlab.lrz.de/vadere/styleguide)
Felix Dietrich's avatar
Felix Dietrich committed
84 85
for the style guide and for how to import the style settings into your IDE.

86
### For Commit Messages
Felix Dietrich's avatar
Felix Dietrich committed
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102

These are examples for a good commit messages:

```
Fix typo in introduction to user guide
```

```
Refactor model initialization

Extracting a new class ModelBuilder because this functionality might be
used in multiple places.
```

Rules:

103 104 105 106 107 108 109
1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how
Felix Dietrich's avatar
Felix Dietrich committed
110 111 112 113 114 115 116 117 118 119

Source: http://chris.beams.io/posts/git-commit/

This article lists good reasons for each rule!
Reasons include:

 - Clean and consistent git-log that also fits in the GitLab user interface
 - Stick to Git standards, e.g. "Merge branch ..." and "Revert ..."

Rules 1, 3, and 4 never hurt and should always be applied.
120

121
### Miscellaneous
122

123
#### Author Tag in JavaDoc
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139

If you make important contributions to a Java class, and especially if you feel
responsible for that class, please add yourself as an author to the class-level
JavaDoc.

Example:

```
/**
 * @author First Last
 * @author Given Sur
 */
public class Foo {
    ...
```

140
#### Tests Required
141 142 143 144

Especially if you implement new functionality, please also provide JUnit tests.
The test classes should be located in the `tests/` folder but in the same
package as the class under test.
145 146 147 148 149 150

## Contributors

People who have contributed code to the project at the Munich University of Applied Sciences (in alphabetical order):

Florian Albrecht, Benjamin Degenhart, Felix Dietrich, Marion Gödel, Benedikt Kleinmeier, Daniel Lehmberg, Jakob Schöttl, Stefan Schuhbäck, Michael Seitz, Swen Stemmer, Isabella von Sivers, Mario Teixeira Parente, Peter Zarnitz, Benedikt Zönnchen