diff --git a/README.md b/README.md index f6b4f82..448ca46 100644 --- a/README.md +++ b/README.md @@ -316,7 +316,9 @@ to direct workflow execution. Community contributions to `ITKRemoteModuleBuildTestPackageAction` are welcome! -Please see [ITK's CONTRIBUTING.MD](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md) +Please read [CONTRIBUTING.md](docs/CONTRIBUTING.md) for testing instructions and best practices +before opening a pull request to contribute your changes. Also see +[ITK's contributing documentation](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md) for general best practices regarding ITK and external modules. Workflow issues may be submitted to the `ITKRemoteModuleBuildTestPackageAction` diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..b10dd64 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,192 @@ +# Contributing to `ITKRemoteModuleBuildTestPackageAction` + +The Insight Toolkit (ITK) open-source community is driven by +involvement from users and developers alike. Contributions +can include new features, bug fixes, or simply +documentation updates. This document describes the community +guidelines to help contributors (like you!) improve the +`ITKRemoteModuleBuildTestPackageAction` repository. + +Check out the project [README](../README.md) +before reading this to better understand the purpose and components +of the `ITKRemoteModuleBuildTestPackageAction` repository. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Creating or Modifying a Workflow](#creating-or-modifying-a-workflow) +- [Testing Your Changes](#testing-your-changes) +- [Creating a Pull Request](#creating-a-pull-request) + +## Prerequisites + +In order to contribute to `ITKRemoteModuleBuildTestPackageAction` you +must have the following: +- A [GitHub](https://github.com/) account; +- A PC with a [git](https://git-scm.com/) client and a text editor of your choice. + +The following are also helpful, but not strictly required: +- A PC running the operating system for which your changes are targeted, + i.e. Windows, Ubuntu (Linux), or MacOS. This will allow you to test changes locally + before pushing to GitHub. +- A Python interpreter of 3.7 or greater for testing wheels locally. + +Before getting started it's helpful to have a working understanding of the following: +- ITK external modules + (see [README discussion](../README.md#motivation)); +- [GitHub Actions](https://docs.github.com/en/actions) and + [continuous integration](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration) + in general; +- [GitHub Actions Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows). + +The following tools and concepts are used in `ITKRemoteModuleBuildTestPackageAction` +and may be helpful or required for contributing: + +- [Bash](https://www.gnu.org/software/bash/) and + [PowerShell](https://learn.microsoft.com/en-us/powershell/) scripting; +- [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/) build tools; +- [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) and + [CDash](https://cmake.org/cmake/help/book/mastering-cmake/chapter/CDash.html) + testing and reporting tools; +- [Python](https://www.python.org/) scripting; +- [Python wheel](https://wheel.readthedocs.io/en/stable/) packaging; + +## Creating or Modifying a Workflow + +GitHub Actions requires that workflows are placed in the [`.github/workflows`](../.github/workflows) directory. +This is where you will find existing workflows and possibly add new workflows. + +To contribute to `ITKRemoteModuleBuildTestPackageAction` you will need to +first [fork](https://docs.github.com/en/github-ae@latest/get-started/quickstart/fork-a-repo) +the repository to your user account on GitHub and then +[clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) +the fork to your local machine. + +### Creating a Workflow + +`ITKRemoteModuleBuildTestPackageAction` is a central repository for Github Actions +reusable workflows for ITK external modules. Before creating a workflow, ask yourself +the following questions: +1. Does my workflow address a problem for ITK external modules that is not + already solved? +2. Does my workflow provide functionality that will generalize to various ITK external modules? +3. Does my workflow provide functionality related to continuous integration such as + building, packaging, and/or testing steps? + +If the answer to all of the above is "yes", then continue on with your new workflow! + +Reference +[Github Actions Reusable Workflow documentation](https://docs.github.com/en/actions/using-workflows/reusing-workflows#creating-a-reusable-workflow) +to get started. You will need to: +1. Create a workflow in the `.github/workflows` folder; +2. Define workflow inputs; +3. Define how jobs will be launched; +4. Define steps that a given job will take. + +### Modifying a Workflow + +Workflows will need to be maintained and updated over time as tools +and technology progress. The best approach to modifying a workflow +is to try to recreate steps on your local system (if possible), +identify failures and fixes, then translate fixes to the resuable +workflow in question. If you encounter an issue that requires +community input you can ask for help on the +[ITK community Discourse forum](https://discourse.itk.org/). + +## Testing Your Changes + +Reusable workflows are intended to _manage continuous integration_ for +ITK external modules in a reusable manner. At the time of writing +there are unfortunately no good options for establishing continuous +integration around proposed changes to reusable workflows themselves, +therefore it is necessary to place an extra burden on the contributors and +maintainers of `ITKRemoteModuleBuildTestPackageAction` to schedule tests themselves. +Fortunately, this translates to severely reduced overhead required of the +general ITK community in maintaining continuous integration on individual +external modules. + +Changes in reusable workflows should be tested through application to +ITK external modules in a user fork. The ideal repositories to use +for testing will depend on the workflow changes under test. + +The [ITKSplitComponents repository](https://github.com/InsightSoftwareConsortium/ITKSplitComponents) +is a good target for testing relatively +simple changes. ITKSplitComponents is a small header-only external module +with a minimum testing suite, Python wrappings, and an example Jupyter Notebook. +Do the following to test against ITKSplitComponents or another ITK external module: +1. Commit your changes to `ITKRemoteModuleBuildTestPackageAction` and + push to make them available on your GitHub user account: +```sh +> git commit +> git push +``` + +2. Fork the [ITKSplitComponents repository](https://github.com/InsightSoftwareConsortium/ITKSplitComponents) + to your GitHub user account and clone to your local machine: +```sh +> cd .. +> git clone git@github.com:/ITKSplitComponents.git +> cd ITKSplitComponents +``` + +3. Create a development branch for your proposed changes: +```sh +> git checkout -b "my-cool-feature" +``` + +4. Update the external module workflow `.yml` file to reference your changes: +```yml +name: Build, test, package + +on: [push,pull_request] + +jobs: + cxx-build-workflow: + uses: /ITKRemoteModuleBuildTestPackageAction/.github/workflows/build-test-cxx.yml@ + with: + itk-cmake-options: '-DITK_BUILD_DEFAULT_MODULES:BOOL=OFF -DITKGroup_Core:BOOL=ON' + + python-build-workflow: + uses: /ITKRemoteModuleBuildTestPackageAction/.github/workflows/build-test-package-python.yml@ + secrets: + pypi_password: ${{ secrets.pypi_password }} +``` + +5. Commit and push your changes: +```sh +> git commit +> git push +``` + +6. Visit `https://github.com//ITKSplitComponents/actions` to view running GHA jobs. + +Other ITK external modules may also be used for testing: +- [ITKBSplineGradient](https://github.com/insightSoftwareConsortium/ITKbsplinegradient) can be + used for building with a dependency on one other ITK external module; +- [ITKUltrasound](https://github.com/KitwareMedical/ITKUltrasound) can be used for building with + dependencies on multiple ITK external modules. + +## Creating a Pull Request + +You can propose changes to the central `InsightSoftwareConsortium` repository by +creating a +[pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). + +1. Visit `https://github.com//ITKRemoteModuleBuildTestPackageAction/pulls` and + click the green "New Pull Request" button to create a pull request for merging changes + from your development branch into `InsightSoftwareConsortium/main`. +2. Describe your changes and create the pull request. + +Each nontrivial `ITKRemoteModuleBuildTestPackageAction` pull request *must* include a +link to a successful GitHub Actions test run in its description. Refer to the +[Testing Your Changes](#testing-your-changes) section for instructions on how to +set up a test run in a user fork of an ITK external module. + +After a repository maintainer reviews, approves, and merges your pull request +your changes will be available to all of the ITK external modules that use +`ITKRemoteModuleBuildTestPackageAction` reusable workflows to drive their testing. +Modules typically use a tagged version of reusable workflows to minimize disruption, +so the changes will be applied to each module when it updates to the workflow +commit hash that includes your changes. + +Thank you for contributing to `ITKRemoteModuleBuildTestPackageAction`!