diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b10dd64..a953e84 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -22,14 +22,17 @@ of the `ITKRemoteModuleBuildTestPackageAction` repository. In order to contribute to `ITKRemoteModuleBuildTestPackageAction` you must have the following: +- A computer; +- An internet connection; - A [GitHub](https://github.com/) account; -- A PC with a [git](https://git-scm.com/) client and a text editor of your choice. +- A [git](https://git-scm.com/) client; +- 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 +- A computer 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. +- A Python interpreter of 3.8 or greater for testing wheels locally. Before getting started it's helpful to have a working understanding of the following: - ITK external modules @@ -64,31 +67,31 @@ the fork to your local machine. ### Creating a Workflow -`ITKRemoteModuleBuildTestPackageAction` is a central repository for Github Actions +`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 +1. Does my workflow provide functionality that will generalize to various ITK external modules? +1. 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) +[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. +1. Define workflow inputs; +1. Define how jobs will be launched; +1. 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 +identify failures and fixes, then translate fixes to the reusable 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/). @@ -96,12 +99,12 @@ community input you can ask for help on the ## Testing Your Changes Reusable workflows are intended to _manage continuous integration_ for -ITK external modules in a reusable manner. At the time of writing +ITK external modules in a reusable manner. As of January 2023 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 +integration around proposed changes to reusable workflows themselves. +It is therefore necessary to place an extra burden on the contributors +to `ITKRemoteModuleBuildTestPackageAction` to schedule tests themselves. +Fortunately, this severely reduces the overhead required of the general ITK community in maintaining continuous integration on individual external modules. @@ -110,31 +113,34 @@ 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: +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: + push to make them available on your GitHub user account. See the + [ITK "Contributing" documentation](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md#commit-messages) + for guidelines on writing commit messages in the ITK ecosystem. ```sh -> git commit -> git push +$ git commit +$ git push ``` -2. Fork the [ITKSplitComponents repository](https://github.com/InsightSoftwareConsortium/ITKSplitComponents) +1. 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 +$ cd .. +$ git clone git@github.com:/ITKSplitComponents.git +$ cd ITKSplitComponents ``` -3. Create a development branch for your proposed changes: +1. Create a development branch for your proposed changes: ```sh -> git checkout -b "my-cool-feature" +$ git checkout -b "my-cool-feature" ``` -4. Update the external module workflow `.yml` file to reference your changes: +1. Update the external module workflow `.yml` file to reference your changes. Either the name of the +development branch or the desired development commit hash may be used to reference workflows. ```yml name: Build, test, package @@ -152,13 +158,13 @@ jobs: pypi_password: ${{ secrets.pypi_password }} ``` -5. Commit and push your changes: +1. Commit and push your changes: ```sh -> git commit -> git push +$ git commit +$ git push ``` -6. Visit `https://github.com//ITKSplitComponents/actions` to view running GHA jobs. +1. Visit `https://github.com//ITKSplitComponents/actions` to view running Github Actions jobs. Other ITK external modules may also be used for testing: - [ITKBSplineGradient](https://github.com/insightSoftwareConsortium/ITKbsplinegradient) can be @@ -175,9 +181,9 @@ creating a 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. +1. Describe your changes and create the pull request. -Each nontrivial `ITKRemoteModuleBuildTestPackageAction` pull request *must* include a +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.