diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..5728359da7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,268 @@ +# Contributing to OPM Simulators + +Thank you for your interest in contributing to the Open Porous Media (OPM) Simulators project! This guide will help you get started with contributing code, documentation, or bug reports. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Process](#development-process) +- [Code Style and Formatting](#code-style-and-formatting) +- [Automated Formatting Tools](#automated-formatting-tools) +- [Testing](#testing) +- [Submitting Changes](#submitting-changes) +- [Reporting Issues](#reporting-issues) +- [Getting Help](#getting-help) + +## Getting Started + +Before contributing, please: + +1. Read the [OPM Project Documentation](https://opm-project.org) +2. Review the [OPM Manual](https://opm-project.org/?page_id=955) +3. Ensure you have the necessary [prerequisites](https://opm-project.org/?page_id=239) installed + +## Development Process + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork locally: + ```bash + git clone https://github.com/YOUR-USERNAME/opm-simulators.git + cd opm-simulators + ``` + +3. Add the upstream repository: + ```bash + git remote add upstream https://github.com/OPM/opm-simulators.git + ``` + +### Create a Feature Branch + +Always create a new branch for your changes: +```bash +git checkout -b feature/your-feature-name +``` + +## Code Style and Formatting + +Maintaining consistent code style is crucial for readability and maintainability. Please follow these guidelines: + +### C++ Code Style + +We use `clang-format` for C++ code formatting. Key settings include: + +- **Line length**: Maximum 120 characters +- **Indentation**: 4 spaces (no tabs) +- **Braces**: Linux style (opening brace on same line for functions) +- **Based on**: WebKit style with modifications + +Run clang-format on your C++ files: +```bash +clang-format -i path/to/your/file.cpp +``` + +### Include File Organization + +Organize `#include` directives in the following order, with blank lines between groups: + +1. **System headers** (C standard library, C++ STL): + ```cpp + #include + #include + #include + ``` + +2. **External library headers** (Dune, etc.): + ```cpp + #include + #include + ``` + +3. **OPM headers from other modules**: + ```cpp + #include + #include + ``` + +4. **Local OPM headers** (from this module): + ```cpp + #include + #include + ``` + +Within each group, maintain **alphabetical order**. + +### Python, Shell, and YAML Files + +- Use **4 spaces** for indentation +- Follow [PEP 8](https://peps.python.org/pep-0008/) for Python code +- Use **lowercase with underscores** for shell script variables +- Maintain consistent quoting style in YAML + +### CMake Files + +- Use **2 spaces** for indentation +- Use lowercase for commands (e.g., `add_library` not `ADD_LIBRARY`) +- Group related commands together with blank lines for readability + +## Automated Formatting Tools + +We recommend using pre-commit hooks to automatically format your code before commits. + +### Pre-commit Setup + +1. **Install pre-commit**: + ```bash + pip install pre-commit + # Or: conda install -c conda-forge pre-commit + # Or: apt install pre-commit (Ubuntu/Debian) + # Or: brew install pre-commit (macOS) + ``` + +2. **Install hooks in your local repository**: + ```bash + pre-commit install + ``` + +3. **What it does**: + - Removes trailing whitespace (preserves Markdown line breaks) + - Ensures files end with exactly one newline + - Runs automatically on every commit + - Supports C/C++, Python, Shell, YAML, CMake, and Markdown files + +4. **Manual usage**: + ```bash + # Run on all files + pre-commit run --all-files + + # Skip hooks for a specific commit + git commit --no-verify + + # Update hook versions + pre-commit autoupdate + ``` + +## Testing + +Before submitting your changes: + +1. **Build the project**: + ```bash + mkdir build && cd build + cmake .. + make + ``` + +2. **Run the test suite**: + ```bash + make test + # Or for more verbose output: + ctest --output-on-failure + ``` + +3. **Run specific tests**: + ```bash + ctest -R test_name + ``` + +4. **Ensure your changes don't break existing functionality** + +## Submitting Changes + +### Commit Messages + +Write clear, descriptive commit messages: + +- First line: Brief summary (50 characters or less) +- Blank line +- Detailed description (wrap at 72 characters) +- Reference relevant issues: `Fixes #123` or `Relates to #456` + +Example: +``` +Add support for polymer flooding in Flow + +This commit introduces polymer flooding capabilities to the Flow +simulator, including: +- Polymer concentration tracking +- Viscosity modifications +- Adsorption modeling + +Fixes #789 +``` + +### Pull Request Process + +1. **Update your branch** with latest upstream changes: + ```bash + git fetch upstream + git rebase upstream/master + ``` + +2. **Push your changes** to your fork: + ```bash + git push origin feature/your-feature-name + ``` + +3. **Create a Pull Request** on GitHub: + - Provide a clear title and description + - Reference any related issues + - Include test results if applicable + - Be responsive to reviewer feedback + +4. **Code Review**: + - Address reviewer comments promptly + - Add new commits for changes (don't force-push during review) + - Once approved, your PR will be merged + +## Reporting Issues + +When reporting issues, please provide: + +1. **Clear description** of the problem +2. **Steps to reproduce** the issue +3. **Expected behavior** vs actual behavior +4. **System information**: + - OS and version + - Compiler and version + - OPM version or commit hash +5. **Build logs** if relevant (see below) + +### Capturing Build Logs + +To capture a build log for issue reporting: + +```bash +LOGFILE=$(date +%Y%m%d-%H%M-)build.log +cmake -E cmake_echo_color --cyan --bold "Log file: $LOGFILE" +script -q $LOGFILE -c 'cmake .. -DCMAKE_BUILD_TYPE=Debug' && +script -q $LOGFILE -a -c 'make -j 4' || +cat CMakeCache.txt CMakeFiles/CMake*.log >> $LOGFILE +``` + +Upload the log file to [gist.github.com](https://gist.github.com) and include the link in your issue. + +## Getting Help + +### Resources + +- **Documentation**: [opm-project.org](https://opm-project.org) +- **Issue Tracker**: [GitHub Issues](https://github.com/OPM/opm-simulators/issues) +- **Mailing List**: [OPM Mailing List](https://opm-project.org/?page_id=358) +- **Build Instructions**: [Build Guide](http://opm-project.org/?page_id=36) + +### Community Guidelines + +- Be respectful and constructive in discussions +- Search existing issues before creating new ones +- Provide context and be specific when asking for help +- Acknowledge contributions from others + +## License + +By contributing to OPM Simulators, you agree that your contributions will be licensed under the GNU General Public License v3.0 or later (GPLv3+). + +--- + +Thank you for contributing to OPM Simulators! Your efforts help advance open-source reservoir simulation technology. \ No newline at end of file