Update README.md

docs/CONTRIBUTING.md

@@ -1,98 +1,129 @@
 # Contributor guidelines
 
+We welcome contributions from users with all levels of experience.
+
+Our aim with k-Wave-II is to keep the barriers to contributing as low as possible while maintaining a tidy and functioning codebase. If something in this guide feels like overkill for your contribution, please feel free to proceed in the simplest way that works and ask for help if needed; the maintainers are happy to guide you. For larger or more complex contributions, following the workflow described here will be important.
+
+If you would like to contribute but are new to it, these are some good ways to get started:
+
+- Add or refine examples and tutorials
+- Help answer or triage issues
+- Improve documentation (clarifications, typos, missing explanations)
+- Suggest small usability improvements
+
+If you are unsure whether something is a suitable contribution, please open an issue or a draft pull request. We are happy to discuss ideas and help you get started.
+
+Before beginning work on a contribution, please read all of this page (Contributor Guidelines), and for more substantial contributions please read:
+
+* [developerIntroduction.md](developerIntroduction.md)
+* [codingStandard.md](codingStandard.md)
+
 ## Development Workflow
 
-The k\-Wave-II development workflow follows [git-flow](https://nvie.com/posts/a-successful-git-branching-model/), modernised for an open-source project to [use forks](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) instead of branches:
+The k-Wave-II development workflow follows a git-flow style organisation (`main`/`develop`/`feature` branches), adapted for open-source development using forks. The default branch is `develop`. The `main` branch is reserved for releases. Code development typically takes place via feature branches that are eventually merged back into the `develop` branch. For more details, see the [maintainer guidelines](maintainerDocs.md)
+
+For most contributions, following these eight steps will make contributing seamless:
 
-- The `main` branch is used only for releases. Any code development branches off and eventually merges back into the `develop` branch, via feature branches. For more details on this workflow, see the [maintainer guidelines](maintainerDocs.md)
-- Start by [creating a fork](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project#creating-your-own-copy-of-a-project) of the GitHub k-Wave-II repo. Make sure you copy all branches, not only the default. Now you have your own copy of the whole repo on GitHub.
-  You can manage that fork as you please, but it is good practice to keep its `main`, `develop`, and feature branches in synch with the upstream k-Wave-II repo, and do your development on different branches.
-- Clone the fork locally to work on your code changes
+### 1. Fork and clone the k-Wave-II repository
+
+* [Fork the repository](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project#creating-your-own-copy-of-a-project). Copy all branches if possible. Now you have your own copy of the whole repo on GitHub.
+* Clone your fork to your local machine, so you can work locally on code changes:
 ```
-git clone https://github.com/YOUR-USER-NAME/k-wave-ii
+git clone <your-fork-url>
 ```
-- Any code development you would like to contribute to k-Wave-II, has to relate to an already reported issue in the upstream repo. For existing issues under active development, an appropriate feature branch would already exist. Those are descriptively named, starting with the issue number, e.g., `62-implement-pml-class`. If an appropriate feature branch does not exist, [open an issue](../#getting-help) in the upstream repo to request one. You will then need to re-synch your fork and `git pull` to get that branch locally.
-- Create a branch off the feature branch you want to contribute to, and switch to it, e.g.
+
+### 2. Set up a development environment
+
+For very small contributions (e.g., documentation updates, minor fixes), you may not need a full development environment. However, a development environment provides an isolated workspace, preventing conflicts with other projects or installed packages on your machine. [conda](https://docs.conda.io/projects/conda/en/latest/index.html) is a popular way to set up an environment.
+* To create an environment from the terminal use:
 ```
-git checkout 62-implement-pml-class
-git switch -c 75-implement-pml-class-getters
+conda create -n kwave
+conda activate kwave
 ```
-Note that, in this case, your development refers to a different issue (`75` in this fictional example), that should ideally be a [sub-issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues) of the larger feature issue (`62` in this example).
-If you want to work on the parent issue directly, use its number instead, together with something that identifies you in the name of the branch, e.g.
+Environments are not tied to any particular folder or repository. The environment (here `kwave`) will remain active until you deactivate it (`conda deactivate`) or close the terminal.
+
+### 3. Install dependencies
+
+* Once your clean environment is activated, install the packages listed in `requirements.txt`, which contain tools (dependencies) used for documentation and development. This can be done in one step:
 ```
-git switch -c 62-implement-pml-class-YOUR_USER_NAME
+pip install -r requirements.txt
 ```
+(On a mac you may have to run `conda install pip` first). Installing these dependencies will only need to be done once. For subsequent sessions, just activate the environment (`conda activate kwave`) and the packages will be there.
+
+### 4. Create a branch
 
-- [Set up a development environment](#setting-up-a-development-environment). This is not needed for the matlab code to run, but for the various tools you will need for development.
-- **Now that you are ready to code, please read the [developers intro](developerIntroduction.md) and [coding standard](codingStandard.md)!**
-- Commit to that branch locally and regularly push your work to the same named branch on the fork.
-- Label commit messages with the issue number, e.g., `git commit -m "#62: Basic class structure"`
-- If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR) from your branch in your fork, to the feature branch in the upstream repo. Likewise, when you think the branch is ready for merging, open a (normal) PR, or convert your draft one to a normal PR, and request a code review.
+* If your fork is not newly created, make sure your fork is up to date with the upstream repository (`k-wave-ii`).
+* Create a new branch from `develop`, choosing a descriptive name. For anything beyond a trivial fix, please use the number of the issue you are working on at the start of the branch name. If there is no suitable issue, please open an issue in the upstream repo.
+```
+git checkout develop
+git switch -c <issue-number-short-descriptive-name>
+```
+For larger or coordinated features, maintainers will organise work using shared feature branches. Please check to see if the relevant feature branch already exists for your issue:
+```
+git branch -r
+```
+Where a relevant feature branch exists, create a branch off the feature branch you want to contribute to, and switch to it, e.g.
+```
+git checkout 62-implement-a-new-feature
+git switch -c 75-implement-a-new-feature-my-part
+```
+or to work on a parent issue directly, please use a branch name that identifies you, e.g.
+```
+git switch -c 62-implement-a-new-feature-<your-username>
+```
 
-For experienced git users, `git rebase` should be avoided if multiple people might be contributing to a branch (use `git merge` instead).
+### 5. Make your changes
 
-## Setting up a Development Environment
+* Now you are ready to make the changes you want to make to the code or documentation.
 
-**1. Create and activate an environment**
-Use an environment manager to create and activate a python environment.
+### 6. Run pre-commit checks
 
-For example, with [conda](https://docs.conda.io/projects/conda/en/latest/index.html):
+One of the dependencies installed above is [pre-commit](https://pre-commit.com/). k-Wave-II uses `pre-commit` to run automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent. It also runs automatically as part of the Continuous Integration (CI) when pull requests are made. Running `pre-commit` locally allows small issues, such as trailing whitespace, to be fixed. These would otherwise cause the CI checks to fail.
 
-```bash
-conda create -n kwave
-conda activate kwave
+* To run pre-commit on all files use
+```
+pre-commit run -a
 ```
 
-**2. Install dependencies**
-Install packages defined in `requirements.txt`:
+### 7. Add, commit, push
 
+* Once you have made your changes and `pre-commit` has corrected anything it finds, add and commit the changed files to your local repo. To make it easier for a reviewer to see what changes you have made, please label commit messages with the issue number and a short description.
 ```
-pip install -r requirements.txt
+git add .
+git commit -m "#<issue-number> Short description of my changes"
+```
+* Push the added files to the remote repository (your fork):
+```
+git push -u origin <my-branch>
 ```
 
-This installs [`mkdocs`](https://www.mkdocs.org/) used to build the documentation (see [Writing and Building the Documentation](developerIntroduction.md#writing-and-building-the-documentation)).
+### 8. Pull request
 
-If you want to skip the pre-commit checks when you commit a change, you can use `git commit --no-verify`. However, the same tests will be run automatically on the CI when you push your changes to GitHub, and they will fail at that point if they identify any required fixes. We strongly suggest you fix any issues identified by pre-commit locally, before committing and pushing to the repository.
+* When your branch is ready for merging, go to GitHub `k-wave-ii` and open a pull request (new pull request →  compare across forks) to merge your changes into the `develop` branch of the upstream `k-wave-ii` repository.
 
-**3. Install pre-commit**
-We use [pre-commit](https://pre-commit.com/) which runs automated checks (formatting, spelling, line endings, etc.) on every `git commit` to keep the codebase consistent.
+The most likely cause of CI test failure for small changes is `pre-commit`; see below how to fix these failures before you commit. If you need feedback or help but your branch is not ready to merge, open a draft pull request (PR). Please avoid rebasing branches that are shared with other contributors. For shared work we recommend using `git merge` instead to avoid disrupting others.
 
-Install and enable it with:
+## Conditions for Merging a PR
 
-```bash
-pre-commit install
-```
+Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo. The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are
 
-To run pre-commit manually:
-
-```bash
-pre-commit run
-```
+- For new features (functions or classes), please add appropriate tests. See the [developer docs](developerIntroduction.md) for more details.
+- All tests should pass. Running tests locally is encouraged but not required as CI will run them automatically when you open a pull request.
+- [Update the documentation](developerIntroduction.md#writing-and-building-the-documentation) and make sure it builds and looks right.
+- Add examples and/or tutorials for substantial new functionality.
+- One approving code review from a maintainer is required.
 
-By default, the pre-commit checks will be run only on the files that changed. If you want to run it on all files, use `pre-commit run -a` instead.
+The code review step is crucial in order to guarantee the quality of code contributions from the community. It is an iterative process, and you will have to address the reviewer's comments and any concerns. Please remember that these comments are intended to improve the software, and should not be taken as a judgement on coding ability.
 
 ## AI and LLM Use
 
 AI tools can be valuable for learning, exploring ideas, and accelerating work. We welcome their thoughtful use. To ensure contributions remain meaningful and contributors continue to grow, we ask that you:
 
 * Understand what you submit. Be able to explain and defend any contribution you make. If you cannot, it is not ready to submit.
 * Stay in the driver's seat. Use AI to support your learning and work, not to replace the effort and critical thinking that make you a better developer.
-* Engage meaningfully. Low-effort, AI-generated submissions (issues, PRs, or proposals) without genuine personal engagement are not acceptable.
-
-Maintainers may ask contributors to explain their work. This is part of our commitment to learning and quality—not a test of whether you used AI, but whether you understood and own what you contributed.
-
-## Conditions for merging a PR
-
-Only the k-Wave-II maintainers can merge PRs into any of the branches of the upstream repo.
-The pull request template will guide you through the requirements to get your changes approved and merged by the maintainers. For reference, those are
-
-- If adding a new function or class, add appropriate tests. See the [developer docs](../developerIntroduction#testing-framework) for more details.
-- All tests, existing or new, should pass. You should strive to run the tests locally before you open the PR, in order to catch errors early, but the Github Actions automation on the k-Wave-II repo will run them automatically as well when you open a PR.
-- [Update the documentation](../developerIntroduction#writing-and-building-the-documentation) and make sure it builds and looks right.
-- Add examples and/or tutorials if you added more substantial functionality.
-- One approving code review by one of the maintainers.
+* Engage meaningfully. Low-effort, AI-generated submissions (issues, PRs, or proposals) without genuine personal engagement will not be accepted.
 
-The code review step is a crucial one, to guarantee the quality of code contributions from the community. It is an iterative process, and you will have to address the reviewer's comments and any concerns. Keep in mind that those comments are given in good faith and not as judgement on anyone's coding ability, and are meant to support our community of developers in creating the best software we can, for all of us to use. Seasoned developers would testify to how much they have learned and improved in their work by receiving reviews on their codes.
+Maintainers may ask contributors to explain their work. This is part of our commitment to learning and quality — it is not a test of whether you used AI but whether you understand what you contributed.
 
 
 ## Legal and Licensing