CONTRIBUTING.md 3.74 KB
Newer Older
1 2
# Contribution guidelines for DuMu<sup>x</sup>

3
DuMu<sup>x</sup> and DUNE are community projects and we are happy about all forms of external contributions.
Bernd Flemisch's avatar
Bernd Flemisch committed
4
Here are many easy things that you can do, like
5 6 7

* read the documentation and tell us where and how it should be improved,
* try to install DuMu<sup>x</sup> on your platform and report bugs if it doesn’t work,
Bernd Flemisch's avatar
Bernd Flemisch committed
8
* fix bugs and open merge requests or send us patches.
9 10 11

If you decide to contribute code please read this contribution guide.

12
## Style guide
Bernd Flemisch's avatar
Bernd Flemisch committed
13
When contributing code to DuMu<sup>x</sup> please follow the [style guide](doc/styleguide.md). Your work will enjoy much smoother sailing if you stick to it with your changes. DuMu<sup>x</sup> is a pretty large project, and a consistent way of doing things really helps a lot when trying to find your way around the code.
14 15 16 17 18

## Contributing

You should get your changes to us in the following way:

Bernd Flemisch's avatar
Bernd Flemisch committed
19 20 21
* Get an account for our GitLab instance (you might need to contact us if you can't create projects at first login).
* Fork the core module that you want to contribute to, just as you would do on GitHub.
* Push your changes to your fork on some branch.
22
* Open a merge request using the branch you pushed your changes to as the source branch and the master of the DuMu<sup>x</sup> repository
Bernd Flemisch's avatar
Bernd Flemisch committed
23 24 25
  as the target branch. GitLab will usually ask you about opening a merge request if you browse it right after pushing to some branch.
* Follow the discussion on the merge request to see what improvements should be done to the branch before merging.
* If you have developer status you don't need to do a fork and you can create branches directly.
26 27

If you have any questions or complaints about this workflow of contributing to DuMu<sup>x</sup>, please ask on the
Bernd Flemisch's avatar
Bernd Flemisch committed
28
[DuMu<sup>x</sup> mailing list](https://listserv.uni-stuttgart.de/mailman/listinfo/dumux).
29 30

## Git
Bernd Flemisch's avatar
Bernd Flemisch committed
31 32 33 34 35 36
* Use Git to your advantage!
* Check out this [great tutorial](https://www.atlassian.com/git/tutorials/setting-up-a-repository) in order to learn how to use it.
* Also check out [Dune's Git best practices](https://www.dune-project.org/doc/guides/git_best_practices/).
* Everything should compile after every single commit.
* Make small commits with changes limited to a single issue / change.
* Format commit messages as follows:
37

Timo Koch's avatar
Timo Koch committed
38 39 40 41 42 43 44 45
    ```
    [topic] Brief description of the change

    Long description containing the status quo,
    the changes the commit introduces and why.
    ```

    where `topic` is usually a foldername, `[assembly]`, a model `[2p2c]`, or any other topic, e.g. `[cmake]`.
46

Bernd Flemisch's avatar
Bernd Flemisch committed
47 48 49 50 51
* Use `git rebase -i master` to update branches to the changes on the master branch.
* Feature branches should be called `feature/my-bla-feature`.
* Bugfix branches should be called `fix/issue-554`.
* Cleanup branches should be called `cleanup/remove-deprecated-bla`.
* Use lower case letters only, and hyphens to separate things.
52 53

## GitLab
Bernd Flemisch's avatar
Bernd Flemisch committed
54 55 56 57 58 59 60
* Open issues for bugs / discussions / feature requests.
* Give issues a meaningful title, focus each issue on a single topic, describe what the problem is and what you tried.
* Open merge request for changes to be merged into master or other branches. Pushing to master is disabled.
* Give merge requests a meaningful title, describe what the problem is, how this is fixed with this merge request.
* If you don't have the permissions to open branches, you might have permissions to do a fork in your own GitLab namespace and open a merge request from your fork into the dumux repository.
* Merge requests get reviewed by at least one main developer.
* If continuous integration (GitLabCI / BuildBot) is enabled for merge requests, the pipeline has to pass before merging anything to master.
61 62 63

## Patches

Bernd Flemisch's avatar
Bernd Flemisch committed
64 65
* Patches can be supplied via the mailing list,
* should be formatted with git format-patch.
66
* TODO: How to format patches