# Contributing to Exudyn

Exudyn is developed by a small group with very limited capacity for code review. That one fact
shapes everything below: **reports, questions and ideas are welcome and are read; code is agreed
before it is written.**

## What helps most

| you want to | do this |
|---|---|
| report something that goes wrong | open a [bug report](https://github.com/jgerstmayr/EXUDYN/issues/new/choose) |
| ask for a feature or a change | open a [feature request](https://github.com/jgerstmayr/EXUDYN/issues/new/choose) |
| ask how to model something | open a [discussion](https://github.com/jgerstmayr/EXUDYN/discussions) — the answer then helps the next person who searches for it |
| write something that does not belong in public | reply.exudyn@gmail.com |

**Start a report with the output of**

```
python -m exudyn info
```

It prints the version, the location of the installed package, which compiled module is loaded,
the Python version and platform, and which optional packages are present. That is what most
answers need to start from, and it saves a round of questions.

The second thing that makes a report answerable in one round is **a script that shows the problem
and nothing else**. Cutting a model down to what still fails is not busywork — it is the step that
most often finds the cause before anyone else has looked.

## Code

The repository is **not open for unsolicited pull requests**, and one that arrives without a prior
agreement will probably not be reviewed. This is not about the quality of the contribution:

- reviewing a change to the C++ core costs more than writing it, and the review capacity is the
  scarce resource here;
- the C++/Python boundary is deliberate and narrow (items are created from validated Python dicts
  dispatched on a type string, not from per-class bindings), and a change that crosses it in a new
  way affects every item;
- large parts of the tree are **generated** — `src/Autogenerated/` from `definitions/`,
  `docs/generated/` from the definitions and the docstrings, `CHANGELOG.md` from the issue
  tracker. A hand edit to any of them survives until the next generator run and no longer.

So: **talk first** — an issue, a discussion or an email. If a change is agreed, it is welcome, and
the rest of this page applies to it.

It would be opened further if there were enough requests for that. Say so if you want it.

## If a change is agreed

Read the two pages that carry the conventions:

- [`docs/dev/CODING_STYLE.md`](docs/dev/CODING_STYLE.md) — naming, headers, and §10 in particular:
  how Exudyn reports an error, and which of the exception types a new check should raise;
- [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) — the issue tracker, the version numbering and the
  gates a change passes before it is committed.

The short form of those gates, which is what a pull request is checked against:

1. **Never edit a generated file.** Change what it is generated from and run
   `python tools/regenerate.py`; the regenerated files belong to the same change. Every generated
   file says in its first line which tool wrote it.
2. **The test suite passes in full**: `python python/testing/runTestSuite.py` (about 20 seconds)
   and `pytest`.
3. **New behaviour has a test**, and a fixed bug has the test that would have caught it.
   A test model is three lines of boilerplate; `docs/dev/WORKFLOW.md`, *What a test model
   looks like*, says which three.
4. **The documentation is updated** where it describes what changed.
5. **The style of the file you are editing is followed**, even where it differs from your own.

Building from source, the environments and the developer driver `exudev` are described in
[`docs/dev/README.md`](docs/dev/README.md) and
[`docs/dev/BUILD.md`](docs/dev/BUILD.md).

## Licence

Exudyn is free software; see [`LICENSE.txt`](LICENSE.txt). A contribution is made under the same
licence as the rest of the project.