# Contributing to Rayleigh
Rayleigh is a community project that lives by the participation of its
members — i.e., including you! It is our goal to build an inclusive
and participatory community so we are happy that you are interested in
participating! 

## Getting started with git and GitHub
GitHub provides a helpful
guide on the process of contributing to an open-source project
[here](https://opensource.guide/how-to-contribute/).

## Asking and answering questions about Rayleigh
The Rayleigh community maintains an active forum hosted by CIG
[here](https://community.geodynamics.org/c/rayleigh).

## Bug reports
It is a great help to the community if you report any bugs that you
may find. We keep track of all open issues related to Rayleigh
[here](https://github.com/geodynamics/Rayleigh/issues).

Please follow these simple instructions before opening a new bug report:

- Do a quick search in the list of open and closed issues for a duplicate of
  your issue.
- Do a google search in the archived mailing list discussions for a
  duplicate of your issue by searching for 

  `your search term site:http://lists.geodynamics.org/pipermail/geodyn/`
- If you did not find an answer, open a new
  [issue](https://github.com/geodynamics/Rayleigh/issues/new) and explain your
  problem in as much detail as possible.
- Attach as much as possible of the following information to your issue:
  - a minimal parameter file that reproduces the issue,
  - the error message you saw on your screen,
  - any information that helps us understand why you think this is a bug, and
    how to reproduce it.

## Making Rayleigh better
Rayleigh is a community project, and we are encouraging all kinds of
contributions. Much
appreciated contributions are new examples (cookbooks, tests, or benchmarks),
extended documentation (every paragraph helps), and in particular fixing typos
or updating outdated documentation. Obviously, we also encourage
contributions to the core functionality in any form! If you consider making a
larger contribution to the core functionality, please open a new
[issue](https://github.com/geodynamics/Rayleigh/issues/new) first, to discuss
your idea with one of the maintainers. This allows us to give you early
feedback and prevents you from spending much time on a project that might already be
planned, or that conflicts with other plans.

To make a change to Rayleigh you should:
- Create a
[fork](https://guides.github.com/activities/forking/#fork) (through GitHub) of
the code base.
- Create a separate
[branch](https://guides.github.com/introduction/flow/) (sometimes called a
feature branch) on which you do your modifications.
- You can propose that your branch be merged into the Rayleigh
code by opening a [pull request](https://guides.github.com/introduction/flow/).
This will give others a chance to review your code. 

If you want to modify the documentation and preview your changes locally, you
can find instructions for compiling the documentation in the [INSTALL](INSTALL)
file.

We follow the philosophy that no pull request (independent of the author) is
merged without a review from one other member of the community, and approval of
one of the maintainers. This applies to maintainers as well as to first-time
contributors. We know that a review can be a daunting process, but pledge to
keep all comments friendly and supportive! We are as
interested in making Rayleigh better as you are!

While this seems very
formal, keeping all of the code review in one place makes it easier to
coordinate changes to the code (and there are usually several people making
changes to the code at once). Please do
not hesitate to ask questions about the workflow on the mailing list if you are
not sure what to do.

If you add new Fortran files or change the module structure of Rayleigh, the
dependencies in the makefile have to be updated. This is done by running `make fdeps` from the
main repository directory, which modifies the file `src/Makefile.fdeps`. Commit
this file along with your changes. You need the `makedepf90` tool on your
development machine to perform this update. `makedepf90` is available in most package managers.

*This is a placeholder for a paragraph about coding conventions*

If you are new to the project then we will work with you to ensure your
contributions are formatted with this style, so please do not think of it as a
road block if you would like to contribute some code.



## Acknowledgment of contributions
While we are grateful for every contribution, there are also several official
ways how your contribution will be acknowledged by the Rayleigh community:
- Every commit that was merged into the Rayleigh repository will make you part of
  the growing group of Rayleigh
  [contributors](https://github.com/geodynamics/Rayleigh/graphs/contributors).
- If you contributed a significant part of the manual (such as a new cookbook,
  benchmark, or subsection), you will be listed as one of the contributing
  authors of the manual.
- Regularly, the Principal Developers of Rayleigh come together and discuss based
  on the contributions of the last years who should be invited to join the
  group of Principal Developers. Criteria that *Principal Developers* should
  match are:

  - A profound understanding of Rayleigh's structure and vision,
  - A proven willingness to further the project's goals and help other users,
  - Significant contributions to Rayleigh (not necessarily only source code,
    also mailing list advice, documentation, benchmarks, tutorials),
  - Regular and active contributions to Rayleigh for more than one year,
    not restricted to user meetings.

  The group of current Principal Developers is listed in the [AUTHORS](AUTHORS)
  file in the main repository.

## License
Rayleigh is published under the [GPL v3 or newer](LICENSE); while you
will retain copyright on your contributions, all changes to the code
must be provided under this common license.
