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

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
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
* fix bugs and open merge requests or send us patches.
9 10 11

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

## Style guide
Bernd Flemisch's avatar
Bernd Flemisch committed
When contributing code to DuMu<sup>x</sup> please follow the [style guide](doc/ 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.
* 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
[DuMu<sup>x</sup> mailing list](
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]( in order to learn how to use it.
* Also check out [Dune's 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:

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]`.

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.
* TODO: How to format patches