👍🎉 Thank you for your interest to contribute to ElmerFEM! 🎉:👍
The following is a set of guidelines for contributing to Elmer, on GitHub. Without wanting to impose too much constraints on your contribution, please see this documents as a general guideline.
I just have a question to ask about Elmer!
What should I know before I get started?
This project and everyone participating in it is governed by the ElmerFEM Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to the ElmerFEM Administrator.
Note: Please refrain from opening an issue here at GitHub to ask a question.]
We maintain an official Elmer forum - that's exactly the place were to put questions (or most likely already find the answers posted)
We expect you to be familiar with the code development philosophy of Elmer. The up-to-date version of Elmer is in repository branch devel, which by name is a constantly changing code-base. Larger separate steps in development take place in separate feature branches that in the end shall be merged into devel. If a new feature to an existing model or even a complete new model we expect a small test case that can be integrated into our ctest test suite that provides a benchmark for the new functionality. Any further new feature to the library and the modules of will then be evaluated against that suite of tests.
This section guides you through submitting a bug report for ElmerFEM. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behaviour 💻 💻, and find related reports 🔎.
Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible.
Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
In order to avoid multiple reporting of bugs, please follow these steps before reporting one
- make sure you are on the correct branch (we only take reports from ´devel`) and that it is up-to-date
- check the current issues filed for this branch to whether the problem already has been mentioned
- make sure the fault of the code is not caused by errors in the inputs
Bugs are tracked as GitHub issues.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don't just say what you did, but explain how you did it.
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
- Best would be to provide the (hopefully small) case that reproduces the behaviour on your side.
- Describe the behaviour you observed after following the steps and point out what exactly is the problem with that behaviour.
Include details about your configuration and environment:
- Which version of Elmer are you using? You should see the version plus the date when compiled in the first output lines of your Elmer simulation,.
- What's the name and version of the OS you are running Elmer on?
- What compiler suite and what flags you used to compile Elmer?
- What hardware Elmer is run on?
- What external libraries are linked into your Elmer version, in particular the MPI version?
This section guides you through submitting an enhancement suggestion for Elmer, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion 📝 and find related suggestions 🔎.
Before creating enhancement suggestions, please check this list as you might find out that you don't need to create one.
- Check whether this enhancement has already been suggested.
- Check, whether there is a dedicated branch of Elmer that already contains that enhancement or has it in development.
Enhancement suggestions are tracked as GitHub issues.
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a step-by-step description of the suggested enhancement in as many details as possible.
- Specify the name and version of the OS you are using.
The process described here has several goals:
- Maintain ElmerFEM's quality
- Fix problems that are important to users
- Engage the community in working toward an ever improved ElmerFEM
- Enable a sustainable system for ElmerFEM maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
- Always make sure your forked branch is derived from a more or less up-to-date
develbranch - Follow the styleguides
- Run all ´ctest´ to verify that the code enhancement do not affect the behaviour of other parts of the code
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
Elmer uses 2008 Fortran standard in which all new code should be provided.
for formatting we use the following rules
- we use 2 space indent
- names functions/subroutines are written in Pascal case (or Upper Camel Case), e.g. OptimizeBandwidth()
- variable names for short variables are small caps, while compound names usually in Pascal case also but there some variation.
- Fortran-language specific elements, such as variable-types (e.g., INTEGER) and properties (e.g., ALLOCATABLE) are written in capital letters
- Comments inside the code
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
- When only changing documentation, include
[ci skip]in the commit title
ElmerFEM model and solver documentation is written in LaTeX and maintained by CSC outside this repository. Part of the documentation is publicly available in https://github.com/ElmerCSC/elmerfem-manuals. There are certain sub-projects (like Elmer/Ice) that provide their own documentation within this repository and use markdown language.
This section lists the labels we use to help us track and manage issues and pull requests.
GitHub search makes it easy to use labels for finding groups of issues or pull requests you are interested in. We encourage you to read about other search filters which will help you write more focused queries.
The labels are loosely grouped by their purpose, but it's not required that every issue has a label from every group or that an issue can't have more than one label from the same group.
Please open an issue on elmerfem/devel if you have suggestions for new labels, and if you notice some labels are missing on some repositories, then please open an issue on that repository.
| Label name | elmerfem/devel 🔎 |
Description |
|---|---|---|
enhancement |
[search][search-elmerfem-repo-label-enhancement] | Feature requests. |
bug |
[search][search-elmerfem-repo-label-bug] | Confirmed bugs or reports that are very likely to be bugs. |
question |
[search][search-eerlmfem-repo-label-question] | Questions more than bug reports or feature requests (e.g. how do I do X). |