|
| 1 | +# Contributing to the MFC Codebase (Multi‑Component Flow Code) |
| 2 | + |
| 3 | +**Multi‑Component Flow Code (MFC)** is an open‑source, high‑performance code for simulating compressible multi‑component, multi‑phase flows. |
| 4 | +We welcome contributions of all kinds—bug fixes, new features, documentation, tests, and issue triage—from both newcomers and experienced developers. |
| 5 | +This guide explains how to set up your environment, follow MFC's coding standards, and navigate the pull-request (PR) process so your work can be merged smoothly. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 1. Setting Up Your Development Environment |
| 10 | + |
| 11 | +1. **Fork and clone** |
| 12 | + ```bash |
| 13 | + git clone https://github.com/<your‑user>/MFC.git |
| 14 | + cd MFC |
| 15 | + git remote add upstream https://github.com/MFlowCode/MFC.git |
| 16 | + ``` |
| 17 | +2. **Build MFC** – follow the [documentation](https://mflowcode.github.io/documentation/md_getting-started.html). For example: |
| 18 | + ```bash |
| 19 | + ./mfc.sh build -j 8 # parallel build with 8 threads |
| 20 | + ``` |
| 21 | +3. **Run the test suite** to verify your environment: |
| 22 | + ```bash |
| 23 | + ./mfc.sh test -j 8 |
| 24 | + ``` |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## 2. Development Workflow |
| 29 | + |
| 30 | +| Step | Action | Notes | |
| 31 | +|------|--------|-------| |
| 32 | +| 1 | **Sync your fork**: `git checkout master && git pull upstream master` | Stay up‑to‑date to avoid merge conflicts. | |
| 33 | +| 2 | **Create a branch**: `git checkout -b feature/<short‑name>` | Keep each branch focused on one logical change. | |
| 34 | +| 3 | **Code, test, document** | Follow the guidelines in §3. | |
| 35 | +| 4 | **Format & lint**: `./mfc.sh format` | CI will re‑check; make it pass locally first. | |
| 36 | +| 5 | **Run tests**: `./mfc.sh test` | All existing and new tests must pass. | |
| 37 | +| 6 | **Commit** (see *Commit Messages* below) | Write clear, atomic commits. | |
| 38 | +| 7 | **Push** & open a **PR** | Be mindful: *every push triggers CI*. Bundle fixes together to avoid dozens of CI runs. | |
| 39 | + |
| 40 | +### Commit Messages |
| 41 | + |
| 42 | +- Start with a concise (≤50 chars) summary in imperative mood: `Fix out‑of‑bounds in EOS module`. |
| 43 | +- Add a blank line, then a detailed explanation. |
| 44 | +- Reference related issues or PRs, e.g., `Fixes #123`. |
| 45 | + |
| 46 | +### Managing CI Runs |
| 47 | + |
| 48 | +Each push to a branch with an open PR runs the full CI matrix (which can take hours). |
| 49 | +Plan your pushes—run tests locally and group changes—so the CI queue is not flooded. |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +## 3. Coding Guidelines and Best Practices |
| 54 | + |
| 55 | +### 3.1 Style, Formatting & Linting |
| 56 | +MFC enforces a project‑wide Fortran style: |
| 57 | +- **Formatter**: `./mfc.sh format` auto‑formats your changes. |
| 58 | +- **Linter**: CI runs several linter checks that spot common Fortran-gotchas (implicit typing, shadowed variables, unused locals, etc.). Fix issues before pushing or the linter will often catch them. |
| 59 | + |
| 60 | +### 3.2 Fypp Metaprogramming |
| 61 | + |
| 62 | +MFC uses [**Fypp**](https://github.com/aradi/fypp), a lightweight Python-based preprocessor, to generate repetitive or accelerator-specific Fortran. |
| 63 | +Key points: |
| 64 | +- Fypp macros live in `include/` directories nested within `src/`. |
| 65 | +- Run `./mfc.sh format` to format the example case files and the source code. |
| 66 | +- When editing `.fpp`, maintain readability, prefer simple macros over deeply nested constructs. |
| 67 | + |
| 68 | +### 3.3 Documentation |
| 69 | + |
| 70 | +- Add or update Doxygen comments in source files. |
| 71 | +- Update Markdown docs under `docs/` if user‑facing behavior changes. |
| 72 | +- Provide a minimal example in `examples/` for each new feature when practical. |
| 73 | + |
| 74 | +### 3.4 Testing |
| 75 | + |
| 76 | +- Add regression tests that fail before your change and pass after. |
| 77 | +- Use `./mfc.sh test --generate` to create golden files for new cases. |
| 78 | +- Keep tests fast; favor small grids and short runtimes. |
| 79 | + |
| 80 | +### 3.5 GPU & Performance |
| 81 | + |
| 82 | +- Ensure code compiles for CPU *and* GPU targets (NVHPC for NVIDIA, Cray for AMD). |
| 83 | +- Profile critical kernels; avoid introducing bottlenecks. |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +## 4. Preparing Your Pull Request |
| 88 | + |
| 89 | +1. **One PR = One logical change**. If you plan a follow‑up change, open an issue describing it and assign yourself for visibility. |
| 90 | +2. **Fill out the PR template**. Remove checkboxes that do **not** apply. |
| 91 | +3. **Describe testing** – list commands, compilers, and any profiling. |
| 92 | +4. **Link issues** – `Fixes #<id>` or `Part of #<id>`. |
| 93 | +5. **Ensure CI passes** before requesting review. |
| 94 | + |
| 95 | +> **Tip** If your change is large, consider splitting it into smaller PRs. Document the intent in an issue so reviewers understand the overall roadmap. |
| 96 | +
|
| 97 | +--- |
| 98 | + |
| 99 | +## 5. Code Review & Merge |
| 100 | + |
| 101 | +- Respond promptly to reviewer comments. |
| 102 | +- Push focused updates; each push re‑runs CI. |
| 103 | +- When all reviews are approved and CI is green, a maintainer will merge your PR. |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## 6. Issue Triage |
| 108 | + |
| 109 | +If you prefer helping with issue management: |
| 110 | +- Comment to clarify reproduction steps. |
| 111 | +- Label issues when you have triage rights. |
| 112 | +- Close fixed issues and reference the PR. |
| 113 | + |
0 commit comments