diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 66f64f46..31495e5d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,75 +1,119 @@ # 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 ``` -- 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 +``` +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- +``` -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 "# Short description of my changes" +``` +* Push the added files to the remote repository (your fork): +``` +git push -u origin ``` -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 @@ -77,22 +121,9 @@ AI tools can be valuable for learning, exploring ideas, and accelerating work. W * 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 diff --git a/docs/README.md b/docs/README.md index 5c6b26a8..272e4dfc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,63 +1,66 @@ # k-Wave-II: A MATLAB toolbox for the simulation of acoustic wave fields -!!! warning "Under Construction" - K‑Wave ii is currently under active development and not public yet. - Documentation, APIs, and features may change without notice. +!!! WARNING "Under Construction" + k‑Wave-II is currently under active development. Documentation, APIs, and features may change without notice. [![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](LICENSE.md) [![codecov](https://codecov.io/gh/ucl-bug/k-wave-ii/graph/badge.svg?token=A8UMTDRF6T)](https://codecov.io/gh/ucl-bug/k-wave-ii) ![unit tests](https://github.com/ucl-bug/k-wave-ii/actions/workflows/tests.yml/badge.svg) ![code quality](https://github.com/ucl-bug/k-wave-ii/actions/workflows/code_quality.yml/badge.svg) ![build docs](https://github.com/ucl-bug/k-wave-ii/actions/workflows/docs.yml/badge.svg) [![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](#contributors-) -k\-Wave-II is an open\-source MATLAB toolbox used to solve partial differential equations, with a particular focus on wave problems in biomedical ultrasound. The unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the bandlimited interpolant, which is useful for implementing staircase free sources, for example. +k\-Wave-II is an open\-source MATLAB toolbox used to solve partial differential equations, with a particular focus on wave problems in biomedical ultrasound. The principal solvers are based on the k-space-corrected pseudospectral time domain method. -k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bug/k-wave) Toolbox, developed +k-Wave-II is a major re-write of the original [k-Wave](https://github.com/ucl-bug/k-wave) Toolbox, developed with the aim of making k-Wave sustainable in the long term. The specific objectives are: +- to re-engineer the code base leveraging object orientated programming, +- to retain the ease-of-use and low barrier-to-entry of k-Wave-I, +- to facilitate greater engagement of the user and contributor communities in code development, +- to improve the development and release process to incorporate best practice, +- and to make k-Wave easier for AI-agents to interact with, eg. for generating training datasets. -with the following aims: - -1. Re-engineering the code base to leverage object orientated programming -and differentiable functions for deep learning and coupled physics problems -2. Extending the algorithms to facilitate general boundary conditions on -arbitrary surfaces, and to increase performance for narrow-band simulations -3. Improving the development and release process to incorporate good -practice and advance long-term sustainability -4. Improving training, user engagement, and support. - -## Releases - -The current release is _XX.YY.ZZ (link to the Changelog/Release notes here)_. +## Getting started -We aim to release a new version of the toolbox every May and November, with patches issued in-between as needed. If you want to use the latest features between releases, you can clone the [github repo](https://github.com/ucl-bug/k-wave-ii/tree/main) and use the `develop` branch. If you choose to do that, please keep in mind that those features might not be complete yet, and therefore we would appreciate your feedback and your patience. +### Installation -Every k-Wave-II release is tested with all releases of MATLAB after the minimum (see [Minimum requirements](#minimum-requirements)), until the latest one before the release was made. +- From the [k-Wave-II GitHub page](https://github.com/ucl-bug/k-wave-ii), find the green Code button and either [clone the repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) or download a zip file of the current version of the codebase. +- Open Matlab. +- Add the location of the k-wave files to the Matlab path, eg. using `addpath()` on the Matlab command line, or the Set Path button on the Home tab. +- Generate the help files, if required, from the Matlab command line. This can take several minutes to run but only needs to be done once as the help files documentation will then be stored. +``` +>> kwave.devtools.GenerateDocumentation +``` +- Import the kwave namespace. This avoids having to prepend all function calls with `kwave.toolbox`, eg. `kgrid = Grid(Nx,dx)` rather than `kgrid = kwave.toolbox.Grid(Nx,dx)`. (If you do this, ensure k-Wave-I is not on the Matlab path to avoid naming conflicts.) +``` +>> import kwave.toolbox.* +``` +- For examples of how to use k-Wave-II, and templates to build upon, see the tutorials in `kwave/tutorials`. -## Getting started ### Minimum requirements -- k-Wave-II requires MATLAB 2022b or later. -- No MATLAB toolboxes are required to use k-Wave-II. However, running the unit tests requires the signal processing toolbox for the reference `sinc` function. -- If importing the k-Wave-II namespace (using `import kwave.toolbox.*`) it is recommended that k-Wave-I is NOT on the MATLAB path to avoid naming conflicts. +- k-Wave-II requires MATLAB R2023b or later. +- No MATLAB toolboxes are required to use k-Wave-II. (Although note that if you want to run the unit tests locally you will require the signal processing toolbox for the reference `sinc` function.) -### Using k-Wave-II +## Releases -For examples of how to use k-Wave-II, have a look at the [tutorials](helpfilesweb/Tutorials/SUMMARY.md) and the [toolbox classes documentation](helpfilesweb/Toolbox_Functions/SUMMARY.md). +k-Wave-II is currently in a pre-release state. We aim, in due course, to release a new version of the toolbox every six months, with patches issued in-between as needed. To use the latest features between releases, you can clone the [github repo](https://github.com/ucl-bug/k-wave-ii/tree/develop) and use the default `develop` branch. Please bear in mind that features on the `develop` branch may not be complete yet, and, in that context, we appreciate your feedback, contributions, and patience. + +Every k-Wave-II release is tested with all releases of MATLAB after the minimum (see [Minimum requirements](#minimum-requirements)), until the latest one before the release was made. ## Getting help -We are a very small team maintaining this toolbox, and we would like it to be community-driven and sustained as much as possible. +We are a very small team maintaining this toolbox, and we would like it to be community-driven and therefore sustainable. -If you would like to report a bug or request a new feature, first check the [existing issues](https://github.com/ucl-bug/k-wave-ii/issues) in the github repo and contribute to the discussion if it is already reported. If it is not, please open a new issue, using the appropriate template. And then, please consider contributing to the fix or improvement (see the section on [contributing](#contributing)). +If you would like to report a bug or request a new feature, first check the [existing issues](https://github.com/ucl-bug/k-wave-ii/issues) in the github repo and contribute to the discussion if it is already reported. If it is not, please open a new issue, using the appropriate template. Also please consider contributing to the fix or improvement (see the section on [contributing](#contributing)). -If you have a question or you need some help, please use the [discussions feature](https://github.com/ucl-bug/k-wave-ii/discussions) in the github repo. Hopefully someone from the community, either a maintainer, developer, or user will be able to assist you. +If you have a question or you need some help, please use the [discussions feature](https://github.com/ucl-bug/k-wave-ii/discussions) in the github repo. Hopefully someone from the community will be able to assist you. ## Contributing -The user community is very welcome to contribute to the code and open pull requests for new features and bug fixes. New developers should read the developer docs first, starting with the [contributor guidelines](CONTRIBUTING.md). +Users are encouraged to contribute to the code and open pull requests for new features and bug fixes. New developers should read the developer docs first, starting with the [contributor guidelines](CONTRIBUTING.md). Anyone who submits code that is accepted into the toolbox will automatically be added to the list of contributors below. -We also welcome further involvement by people wishing to review developers' code contributions and help the community of developers grow. Please contact the maintainers if you are interested in becoming a code reviewer. +We also encourage involvement by those able to review developers' code contributions. Please contact the maintainers if you are interested in becoming a code reviewer. ## Development lead -k‑Wave‑II builds on long‑standing collaborations and the contributions of many researchers, building on foundational work by Bradley Treeby, Ben Cox, and Jiri Jaros. Its ongoing development is guided and maintained by [the UCL Biomedical Ultrasound Group](http://bug.medphys.ucl.ac.uk/). +k‑Wave‑II builds on long‑standing collaborations and the contributions of many researchers to k-Wave-I, including foundational work by Bradley Treeby, Ben Cox, and Jiri Jaros. Its ongoing development is guided and maintained by [the UCL Biomedical Ultrasound Group](https://github.com/ucl-bug). ## Contributors diff --git a/docs/codingStandard.md b/docs/codingStandard.md index 7d144e99..374c104a 100644 --- a/docs/codingStandard.md +++ b/docs/codingStandard.md @@ -1,6 +1,6 @@ # Coding Standard -MATLAB coding standard used for k\-Wave II. +MATLAB coding standard used for k-Wave-II. ## Naming diff --git a/docs/developerIntroduction.md b/docs/developerIntroduction.md index b7529134..561a3aba 100644 --- a/docs/developerIntroduction.md +++ b/docs/developerIntroduction.md @@ -1,20 +1,20 @@ # Developer Introduction -Introduction to k\-Wave II for developers. +Introduction to k-Wave-II for developers. ## Overview -k\-Wave II is an open\-source MATLAB toolbox used to solve differential equations, with a particular focus on wave problems in acoustics. The unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the band\-limited interpolant, which is useful for implementing stair\-case free sources, for example. +k-Wave-II is an open\-source MATLAB toolbox used to solve differential equations, with a particular focus on wave problems in acoustics. The unifying thread for the solvers is that spatial gradients are computed using a Fourier collocation spectral method. This has many advantages, including spectral convergence for smooth functions, and a known analytical form for the band\-limited interpolant, which is useful for implementing stair\-case free sources, for example. -The main components of the toolbox are written using an object\-orientated programming design approach, primarily using `handle` classes. Sets of functionality (such as medium inputs for a particular solver) are grouped into classes. Base classes are used for common functionality that needs to be re\-used multiple times. This adheres to the don't repeat yourself (DRY) software development principle. Some additional helper functions with limited scope are written as standalone functions. +The main components of the toolbox are written using an object-orientated programming design approach, primarily using `handle` classes. Sets of functionality (such as medium inputs for a particular solver) are grouped into classes. Base classes are used for common functionality that needs to be reused multiple times. This adheres to the don't repeat yourself (DRY) software development principle. Some additional helper functions with limited scope are written as standalone functions. The software is written with the following four guiding principles, in decreasing order of importance: -1. **The code is accurate.** The solvers should avoid narrow scope assumptions which are not always applicable. The code should also implement appropriate input validation and error handling, and be covered by appropriate tests (see [Testing Framework](#testing-framework) (testingFramework.md) for further details). -2. **The code is easy to use.** Careful thought should be given to the class interfaces and default values, and the user\-facing API should be as stable as possible over time. All code should be well documented, and the documentation should include user examples and tutorials. Code should also provide sufficient feedback and warnings to guide users. -3. **The code is sustainable.** The development, testing, and release workflows should be sufficiently automated that it is straightforward to implement new features and bug fixes. All code should follow the [Coding Standard](codingStandard.md). +1. **The code is accurate.** The solvers should avoid narrow scope assumptions which are not always applicable. The code should also implement appropriate input validation and error handling, and be covered by appropriate tests (see [Testing Framework](#testing-framework) for further details). +2. **The code is easy to use.** Careful thought should be given to the class interfaces and default values, and the user-facing API should be as stable as possible over time. All code should be well-documented, and the documentation should include user examples and tutorials. Code should also provide sufficient feedback and warnings to guide users. +3. **The code is sustainable.** The development, testing, and release workflows should be sufficiently automated that it is straightforward to implement new features and bug fixes. All code should follow the [Coding Standard](codingStandard.md). 4. **The code is fast.** Code should be profiled regularly, and where possible, refactored to improve computational efficiency. ## Repository Structure @@ -24,15 +24,15 @@ The code is grouped into [package folders](https://uk.mathworks.com/help/matlab/ ``` ├── .github │ ├── ISSUE_TEMPLATE (GitHub issue templates) - │ ├── PULL_REQUEST_TEMPLATE (GitHub pull request template) - │ └── workflows (GitHub actions) + │ ├── pull_request_template (GitHub pull request template) + │ └── workflows (GitHub actions) ├── +kwave │ ├── +devtools (Developer tools) | ├── +docfiles (Documentation files) │ │ └── +general (Additional Documentation Pages) │ ├── +legacy (Copy of k-Wave I) │ ├── +tests (Tests) - │ │ ├── +legacy (Regression tests against k-Wave I) + │ │ ├── +legacy (Regression tests against k-Wave-I) │ │ ├── +linting (Linting tests) │ │ └── +unit (Unit tests) │ ├── +toolbox (Main classes and functions) @@ -43,14 +43,13 @@ The code is grouped into [package folders](https://uk.mathworks.com/help/matlab/ └── helpfilesweb (Created and populated at md documentation generation time) ``` -## Writing And Building The Documentation +## Writing and Building the Documentation -Part of the success of k\-Wave can be attributed to the good documentation, both of the individual functions and classes, and the examples. All code should be documented as outlined in the [Coding Standard](codingStandard.md). It can often be easiest to start with the [documentation template](helpfilesweb/classDocsExample.md). +Part of the success of k-Wave can be attributed to the good documentation, both of the individual functions and classes, and the examples. All code should be documented as outlined in the [Coding Standard](codingStandard.md). It can often be easiest to start with the documentation template `docs/helpfilesweb/Utility_Functions/classDocsExample.md`. When adding a new class or function, examples should be added. If the code usage is relatively straightforward, examples can be included directly in the help documentation for that class or function. For more complex classes (e.g., the solver classes), longer tutorials or examples should be provided. -1. **Tutorials:** These are worked examples stored as `.m` files in the `kwave.tutorials` name space. For tutorials, each block of code should be surrounded by a discussion guiding the user through the example. The discussion should be written using [publishing markup](https://uk.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html)[*](#note). Similar to k\-Wave I, concepts introduced in other tutorials do not need to be re\-introduced. Try and focus on a relatively small number of new concepts in each tutorial. The tutorial code should generally run fast on basic hardware (< 1 min). -2. **Examples:** These are illustrative examples stored as `.m` files in the `kwave.examples` name space. Examples have a wider scope than tutorials, and may demonstrate a real\-world simulation using realistic grid sizes for example (so do not necessarily need to run fast). Examples should contain a comprehensive description of what the example does in the description of the file, but does not need to have long step\-by\-step. +**Tutorials:** These are worked examples stored as `.m` files in the `kwave.tutorials` name space. For tutorials, each block of code should be surrounded by a discussion guiding the user through the example. The discussion should be written using [publishing markup](https://uk.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html)[*](#note). Similar to k-Wave-I, concepts introduced in other tutorials do not need to be re-introduced. Focus on a small number of new concepts in each tutorial. The tutorial code should generally run fast on basic hardware (< 1 min). Please remember to also add the new class, function or tutorial/example file in the appropriate section header file (`Toolbox_Functions.m`, `Tutorials.m` or `Utility_Functions.m`). @@ -61,7 +60,7 @@ According to the matlab documentation, This means that all the text within a section (starting with `%%`) has to come in one continuous area of `%`s in order for it to render. If executable code is interleaved with it, the rest of the text is not rendered. A workaround is to include the code we want to run in the comments area, and duplicate it after each block in order for it to run and produce the plots. Please have a look at the existing tutorials for examples. -### Building The Documentation +### Building the Documentation _MATLAB R2023b or later is required to build the documentation._ @@ -76,20 +75,19 @@ mkdocs serve --livereload ``` and viewed in a browser in `http://127.0.0.1:8000/` for debugging purposes (watch the output of the above command for this address). -## Logging And Errors +## Logging and Errors Logging messages help users understand code settings and status, and help developers debug code. In k\-Wave\-II, all logging messages (including warnings and errors) should be printed using the `kwave.toolbox.Logger` class. This provides a consistent interface, allow adjusting the verbosity of the output messages, and allows piping the logging messages to an external file. -## Toolboxes And External Code +## Toolboxes and External Code The core functionality of k\-Wave\-II should not depend on any MATLAB toolboxes. This is to minimise the requirements for non\-academic users who must purchase a MATLAB license to use k\-Wave. Tests can (and do) depend on additional toolboxes, as this dependency is fulfilled by the GitHub runners (both private and public). - If considering using other external code or libraries (e.g., from the file exchange), this should be flagged first on the issue or pull request. This way, a discussion can be had about the cost of introducing the dependency, and any potential licensing issues. ## Testing Framework -k\-Wave uses the [class\-based unit testing framework](https://uk.mathworks.com/help/matlab/class-based-unit-tests.html). There are several test levels (defined in `kwave.tests.TestType`), each of which lives in its own namespace: +k-Wave-II uses the [class\-based unit testing framework](https://uk.mathworks.com/help/matlab/class-based-unit-tests.html). There are several test levels (defined in `kwave.tests.TestType`), each of which lives in its own namespace: - **`+unit`:** Unit tests validate individual components of a function or class in isolation. - **`+linting`:** Linting checks assess code for stylistic and syntactical correctness. @@ -104,7 +102,6 @@ Each top level class or function should have at least one corresponding unit tes The filenames for all tests should start with `Test`. Unit tests should be named `TestClassName` or `TestFunctionName`. Other tests should be given sensible descriptive names. - The linting tests check for code complexity using [cylomatic complexity](https://uk.mathworks.com/help/matlab/matlab_prog/measure-code-complexity-using-cyclomatic-complexity.html), which is a measure of the decision structure complexity of the code. The complexity of all files changed in a pull request is automatically added to pull requests as part of the code checks action. While a particular number isn't enforced, both developers and reviewers should consider whether a re\-factoring is appropriate if the cylomatic complexity is above 10. To run the tests locally, call: diff --git a/docs/maintainerDocs.md b/docs/maintainerDocs.md index 820a2652..ed027dcb 100644 --- a/docs/maintainerDocs.md +++ b/docs/maintainerDocs.md @@ -1,8 +1,6 @@ # Maintainer guidelines -The [git-flow](https://nvie.com/posts/a-successful-git-branching-model/) workflow is summarised in the following graph, taken from Vincent Driessen's blog post. The only difference between this model and the one we are using in k-Wave-II, is that contributors do not commit changes directly into the feature branches, but they open Pull Requests (PRs) into them from their own forks of the repo. - -Toolbox releases distributed via Matlab are built from the `main` branch (`master` in the graph), and this is what most users are expected to use. If someone wants access to the latest features, they will need to check out and use the `develop` branch, therefore this branch should be in a usable state, even if it does not have the full, release-ready functionality. All other branches are for development purposes. +The [git-flow](https://nvie.com/posts/a-successful-git-branching-model/) workflow is summarised in the following graph, taken from Vincent Driessen's blog post. We largely follow this model, in which `main` ('master' on this figure) is reserved for releases and the default branch is `develop`. Toolbox releases distributed via Matlab are built from the `main` branch, and this is what most users are expected to use. If someone wants access to the latest features, they will need to check out and use the `develop` branch, therefore this branch should be in a usable state, even if it does not have the full, release-ready functionality. All other branches are for development purposes. As noted in the [contributor guidelines](CONTRIBUTING.md), one difference between this model and the one we are using in k-Wave-II, is that contributors do not commit changes directly into `develop` or the feature branches, but they open Pull Requests (PRs) into them from their own forks of the repo. ![alt text](git-model.png "The git-flow workflow by Vincent Driessen") @@ -13,12 +11,11 @@ Maintainers should review issues regularly and place them appropriately in the r Feature branches should branch off `develop` and bugfix branches off whichever is the most stable branch the bug is found in. - ## Development All the branches of the repo are protected, meaning that contributors (including maintainers) cannot commit changes directly to them, they can only open PRs. Additionally, only maintainers can create branches in the main repo. -Therefore all development is done in contributors' forks, on branches that they have branched off feature branches in their fork. When they are ready to merge their changes, they open a PR into the main repo's corresponding feature branch, and request a code review from the maintainers or code reviewers. +Therefore all development is done in contributors' forks, on branches that they have branched off feature branches or `develop` in their fork. When they are ready to merge their changes, they open a PR into the main repo's corresponding feature branch or `develop`, and request a code review from the maintainers or code reviewers. When reviewing contributors' PRs, follow the checklist in the PR template, and check items off as you progress. You should check that @@ -26,18 +23,18 @@ When reviewing contributors' PRs, follow the checklist in the PR template, and c - All tests, existing or new, pass. - Documentation is updated and builds correctly. -You should also review the code changes themselves. Please be constructive and respectful in your comments and support contributors to improve their code. Once they address your concerns, resolve the conversation and when you are satisfied with the code changes overall, approve them. +You should also review the code changes themselves. Please be constructive and kind in your comments and support contributors to improve their code. When they have addressed your concerns resolve the conversation, and when you are satisfied with the code changes overall approve them. *If you think you need to take over development on someone else's PR, always ask them first.* -Only maintainers can merge PRs into the feature branch. Merges need at least one approving review and all the automated tests to pass. You should also make sure that you have ticked all the checkboxes on the template. Once all this is done you can merge, using [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits). Individual commits will still be accessible on GitHub in the (now closed) PR. +Only maintainers can merge PRs into a feature branch or `develop`. Merges need at least one approving review and all the automated tests to pass. You should also make sure that you have ticked all the checkboxes on the template. Once all this is done you can merge, using [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits). Individual commits will still be accessible on GitHub in the (now closed) PR. ## Branch management -Once a feature reaches a certain maturity, maintainers can choose to merge the related branch into `develop`, to let adventurous users try it out. You will probably have to resolve some conflicts at that point. +Once a feature reaches a certain maturity, maintainers can choose to merge the related branch into `develop`, to let adventurous users try it out. They will probably have to resolve some conflicts at that point. Then development can continue in the feature branch, or if it is complete, the maintainers can lock the branch and prevent further commits to it. Feature branches should not be deleted (and cannot be deleted once locked).