|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: � 2021-2022 MONAI Consortium |
| 3 | + SPDX-License-Identifier: Apache License 2.0 |
| 4 | +--> |
| 5 | +- [Introduction](#introduction) |
| 6 | + - [Communicate with us](#communicate-with-us) |
| 7 | +- [The contribution process](#the-contribution-process) |
| 8 | + - [Preparing pull requests](#preparing-pull-requests) |
| 9 | + - [Submitting pull requests](#submitting-pull-requests) |
| 10 | + - [Release a new version](#release-a-new-version) |
| 11 | + |
| 12 | + |
| 13 | +## Introduction |
| 14 | + |
| 15 | +Welcome to Project MONAI Deploy Workflow Manager! We're excited you're here and want to contribute. This documentation is intended for individuals and institutions interested in contributing to the MONAI Deploy Workflow Manager. MONAI Deploy Workflow Manager is an open-source project. As such, its success relies on its community of contributors willing to keep improving it. Therefore, your contribution will be a valued addition to the code base; we ask that you read this page and understand our contribution process, whether you are a seasoned open-source contributor or a first-time contributor. |
| 16 | + |
| 17 | +### Communicate with us |
| 18 | + |
| 19 | +We are happy to talk with you about your MONAI Deploy Workflow Manager needs and your ideas for contributing to the project. One way to do this is to create an [issue](https://github.com/Project-MONAI/monai-deploy-workflow-manager/issues/new/choose) by discussing your thoughts. It might be that a very similar feature is under development or already exists, so an issue is a great starting point. If you are looking for an issue to resolve that will help Project MONAI Deploy Workflow Manager, see the [*good first issue*](https://github.com/Project-MONAI/monai-deploy-workflow-manager/labels/good%20first%20issue) and [*help wanted*](https://github.com/Project-MONAI/monai-deploy-workflow-manager/labels/help%20wanted) labels. |
| 20 | + |
| 21 | +## The contribution process |
| 22 | + |
| 23 | +_Pull request early_ |
| 24 | + |
| 25 | +We encourage you to create pull requests early. It helps us track the contributions under development, whether they are ready to be merged or not. Change your pull request's title to begin with `[WIP]` or [create a draft pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests) until it is ready for formal review. |
| 26 | + |
| 27 | +### Preparing pull requests |
| 28 | + |
| 29 | +This section highlights all the necessary preparation steps required before sending a pull request. |
| 30 | +To collaborate efficiently, please read through this section and follow them. |
| 31 | + |
| 32 | +* [Checking the coding style](#checking-the-coding-style) |
| 33 | +* [Test Projects](#test-projects) |
| 34 | +* [Building documentation](#building-the-documentation) |
| 35 | + |
| 36 | +#### Checking the coding style |
| 37 | + |
| 38 | +##### C# Coding Style |
| 39 | + |
| 40 | +We follow the same [coding style](https://github.com/dotnet/runtime/blob/master/docs/coding-guidelines/coding-style.md) as described by [dotnet](https://github.com/dotnet)/[runtime](https://github.com/dotnet/runtime) project. |
| 41 | + |
| 42 | + |
| 43 | +The general rule we follow is "use Visual Studio defaults" or simply to [CodeMaid](https://marketplace.visualstudio.com/items?itemName=SteveCadwallader.CodeMaid) extension. |
| 44 | + |
| 45 | +1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces, but the block must be properly indented on its line and must not be nested in other statement blocks that use braces (See rule 17 for more details). One exception is that a `using` statement is permitted to be nested within another `using` statement by starting on the following line at the same indentation level, even if the nested `using` contains a controlled block. |
| 46 | +2. We use four spaces of indentation (no tabs). |
| 47 | +3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix internal and private instance fields with `_`, static fields with `s_`, and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (e.g. `static readonly` not `readonly static`). Public fields should be used sparingly and use PascalCasing with no prefix when used. |
| 48 | +4. We avoid `this.` unless necessary. |
| 49 | +5. We always specify the visibility, even if it's the default (e.g. |
| 50 | + `private string _foo' not `string _foo'). Visibility should be the first modifier (e.g. |
| 51 | + `public abstract` not `abstract public`). |
| 52 | +6. Namespace imports should be specified at the top of the file, *outside* of `namespace` declarations should be sorted alphabetically. |
| 53 | +7. Avoid more than one empty line at any time. For example, do not have two |
| 54 | + blank lines between members of a type. |
| 55 | +8. Avoid spurious-free spaces. |
| 56 | + For example, avoid `if (someVar == 0)...`, where the dots mark the spurious-free spaces. |
| 57 | + Consider enabling "View White Space (Ctrl+R, Ctrl+W)" or "Edit -> Advanced -> View White Space" if using Visual Studio to aid detection. |
| 58 | +9. If a file happens to differ in style from these guidelines (e.g. private members are named `m_member` |
| 59 | + rather than `_member`), the existing style in that file takes precedence. |
| 60 | +10. We only use `var` when it's obvious what the variable type is (e.g. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`). |
| 61 | +11. We use language keywords instead of BCL types (e.g. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (e.g. `int.Parse` instead of `Int32.Parse`). See issue [#13976](https://github.com/dotnet/runtime/issues/13976) for examples. |
| 62 | +12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop. |
| 63 | +13. We use "`nameof(...)` "instead of ``` "..." ``` whenever possible and relevant. |
| 64 | +14. Fields should be specified at the top within type declarations. |
| 65 | +15. When including non-ASCII characters in the source code, use Unicode escape sequences (\uXXXX) instead of literal characters. Literal non-ASCII characters occasionally get garbled by a tool or editor. |
| 66 | +16. When using labels (for goto), indent the label one less than the current indentation. |
| 67 | +17. When using a single-statement if, we follow these conventions: |
| 68 | + - Never use single-line form (for example: `if (source is null) throw new ArgumentNullException("source");`) |
| 69 | + - Using braces is always accepted and required if any block of an `if`/`else if`/.../`else` compound statement uses braces or if a single statement body spans multiple lines. |
| 70 | + - Braces may be omitted only if the body of *every* block associated with an `if`/`else if`/.../`else` compound statement is placed on a single line. |
| 71 | + |
| 72 | +An [EditorConfig](https://editorconfig.org "EditorConfig homepage") file (`.editorconfig`) has been provided at the root of the runtime repository, enabling C# auto-formatting conforming to the above guidelines. |
| 73 | + |
| 74 | + |
| 75 | +##### License information |
| 76 | + |
| 77 | +All source code files should start with this paragraph: |
| 78 | + |
| 79 | +``` |
| 80 | +// SPDX-FileCopyrightText: © [YEAR]-[YEAR] MONAI Consortium |
| 81 | +// SPDX-License-Identifier: Apache License 2.0 |
| 82 | +``` |
| 83 | + |
| 84 | +#### Test Projects |
| 85 | + |
| 86 | +All C# projects reside in their directory, including a `Tests/` subdirectory. |
| 87 | +Test projects are also linked in the main solution file [Monai.Deploy.WorkloadManager.sln](src/Monai.Deploy.WorkloadManager.sln) and can be executed either using Visual Studio's *Test Explorer* or with the `dotnet test` command line. |
| 88 | + |
| 89 | + |
| 90 | +_If it's not tested, it's broken_ |
| 91 | + |
| 92 | +An appropriate set of tests should accompany all new functionality. |
| 93 | +MONAI Deploy Workflow Manager functionality has plenty of unit tests from which you can draw inspiration, and you can reach out to us if you are unsure how to proceed with testing. |
| 94 | + |
| 95 | + |
| 96 | +#### Building the documentation |
| 97 | + |
| 98 | +Documentation for MONAI Deploy Workflow Manager is located at `docs/` and requires [DocFX](https://dotnet.github.io/docfx/) to build. |
| 99 | + |
| 100 | +Please follow the [instructions](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool) to install Mono and download the DocFX command-line tool to build the documentation. |
| 101 | + |
| 102 | +```bash |
| 103 | +[path-to]/docfx.exe docs/docfx.json |
| 104 | +``` |
| 105 | + |
| 106 | +#### Automatic code formatting |
| 107 | + |
| 108 | +Install [CodeMaid](https://marketplace.visualstudio.com/items?itemName=SteveCadwallader.CodeMaid) extension for Visual Studio or |
| 109 | +**SHIFT+ALT+F** in Visual Studio Code. |
| 110 | + |
| 111 | +#### Signing your work |
| 112 | + |
| 113 | +MONAI enforces the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) on all pull requests. |
| 114 | +All commit messages should contain the `Signed-off-by` line with an email address. The [GitHub DCO app](https://github.com/apps/dco) is deployed on MONAI. The pull request's status will be `failed` if commits do not contain a valid `Signed-off-by` line. |
| 115 | + |
| 116 | +Git has a `-s' (or `--signoff`) command-line option to append this automatically to your commit message: |
| 117 | + |
| 118 | +```bash |
| 119 | +git commit -s -m 'a new commit' |
| 120 | +``` |
| 121 | + |
| 122 | +The commit message will be: |
| 123 | + |
| 124 | +```text |
| 125 | + a new commit |
| 126 | +
|
| 127 | + Signed-off-by: Your Name <[email protected]> |
| 128 | +``` |
| 129 | + |
| 130 | +Full text of the DCO: |
| 131 | + |
| 132 | +```text |
| 133 | +Developer Certificate of Origin |
| 134 | +Version 1.1 |
| 135 | +
|
| 136 | +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. |
| 137 | +1 Letterman Drive |
| 138 | +Suite D4700 |
| 139 | +San Francisco, CA, 94129 |
| 140 | +
|
| 141 | +Everyone is permitted to copy and distribute verbatim copies of this |
| 142 | +license document, but changing it is not allowed. |
| 143 | +
|
| 144 | +
|
| 145 | +Developer's Certificate of Origin 1.1 |
| 146 | +
|
| 147 | +By making a contribution to this project, I certify that: |
| 148 | +
|
| 149 | +(a) The contribution was created in whole or in part by me and I |
| 150 | + have the right to submit it under the open source license |
| 151 | + indicated in the file; or |
| 152 | +
|
| 153 | +(b) The contribution is based upon previous work that, to the best |
| 154 | + of my knowledge, is covered under an appropriate open source |
| 155 | + license and I have the right under that license to submit that |
| 156 | + work with modifications, whether created in whole or in part |
| 157 | + by me, under the same open source license (unless I am |
| 158 | + permitted to submit under a different license), as indicated |
| 159 | + in the file; or |
| 160 | +
|
| 161 | +(c) The contribution was provided directly to me by some other |
| 162 | + person who certified (a), (b) or (c) and I have not modified |
| 163 | + it. |
| 164 | +
|
| 165 | +(d) I understand and agree that this project and the contribution |
| 166 | + are public and that a record of the contribution (including all |
| 167 | + personal information I submit with it, including my sign-off) is |
| 168 | + maintained indefinitely and may be redistributed consistent with |
| 169 | + this project or the open source license(s) involved. |
| 170 | +``` |
| 171 | + |
| 172 | +### Submitting pull requests |
| 173 | + |
| 174 | +#### Branching |
| 175 | + |
| 176 | +- `main`: the `main` branch is **always ready** with only completed, tested, and verified features. The CI automatically triggers an official build when a PR is merged into the branch. |
| 177 | +- `develop`: the `develop` branch is the active development branch and is for features that are ready for testing. Releases made in this branch are prefixed with `beta`. |
| 178 | +- `release/`: `release` branches are created when a new official release is imminent and does not accept new features except bug fixes. Releases made in this branch are prefixed with `rc`. A pull request shall be created targeting `main` and `develop`. |
| 179 | +- `feature/`: `feature` branches are created for a specific branch. Releases made in this branch are prefixed with `alpha.{branchName}`. A pull request shall be created when the feature is ready, targeting `develop` branch. |
| 180 | + |
| 181 | +#### Begin with Your Contribution Journey with a Pull Request |
| 182 | + |
| 183 | +All code changes must be done via [pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests). |
| 184 | + |
| 185 | +1. Create a new ticket or take a known ticket from [the issue list][issue list]. |
| 186 | +1. Check if there's already a branch dedicated to the task. |
| 187 | +1. If the task has not been taken, [create a new branch in your fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) of the codebase named `[ticket_id]-[task_name]`. |
| 188 | +For example, branch name `{username}/19-ci-pipeline-setup` corresponds to issue #19. |
| 189 | +1. Ideally, the new branch should be based on the latest `develop` branch. |
| 190 | +1. Make changes to the branch ([use detailed commit messages if possible](https://chris.beams.io/posts/git-commit/)). |
| 191 | +1. Make sure that new tests cover the changes and the changed codebase [passes all tests locally](#test-projects). |
| 192 | + |
| 193 | + |
| 194 | +##### When You Are Ready to Merge |
| 195 | +1. [Create a new pull request](https://help.github.com/en/desktop/contributing-to-projects/creating-a-pull-request) from the task branch to the `develop` branch, with detailed descriptions of the purpose of this pull request by filling out the [template](./.github/pull_request_template.md). |
| 196 | +1. Make sure all checks are successful |
| 197 | +1. Complete tasks listed in the template as much as possible |
| 198 | +1. Wait for reviews; if there are reviews, make point-to-point responses, make further code changes if needed. |
| 199 | +1. If there are conflicts between the pull request branch and the target branch, pull the changes from the target branch and resolve the conflicts locally. |
| 200 | +1. Reviewer and contributor may have discussions back and forth until all comments are addressed. |
| 201 | +1. Wait for the pull request to be merged. |
| 202 | + |
| 203 | + |
| 204 | + |
| 205 | +### Release a new version |
| 206 | + |
| 207 | +A PR is made from a `release/` branch to the `main` branch when a new official release is ready. The CI process validates & builds all components required, composes the release notes, and publishes the build in the [Releases](https://github.com/Project-MONAI/monai-deploy-workflow-manager/releases) section and any Docker images in the [Packages](https://github.com/orgs/Project-MONAI/packages?repo_name=monai-deploy-workflow-manager) section. |
| 208 | + |
| 209 | +- [Actions](https://github.com/Project-MONAI/monai-deploy-workflow-manager/actions) |
| 210 | +- [Issues](https://github.com/Project-MONAI/monai-deploy-workflow-manager/issues) |
| 211 | +- [Milestones](https://github.com/Project-MONAI/monai-deploy-workflow-manager/milestones) |
| 212 | +- [Releases](https://github.com/Project-MONAI/monai-deploy-workflow-manager/releases) |
| 213 | +- [Packages](https://github.com/orgs/Project-MONAI/packages?repo_name=monai-deploy-workflow-manager) |
0 commit comments