Windows Machine Config Operator is Apache 2.0 licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on commit message formatting and other resources to help get contributions into the project.
To get an overview of what the WMCO does, please take a look at the README first. In order to work with the codebase, you'll need to understand a few basic git concepts. Follow the steps below to set up your environment to get started.
- Fork the repository on GitHub.
- Clone the forked repository outside your go path
- Create a topic branch, branched off of master.
- Make commits of logical units as you work
Thank you for contributing to the Windows Machine Config Operator!
Before opening a pull request, be sure that your changes have been tested, documented, and checked for style. Once you think your PR is ready for review, be sure to check that you have
- Fetched from upstream WMCO
- Rebased your changes against your root branch
- Run the tests locally
- Linted your changes with
make lint- Fixed any import issues found by running
make imports
- Fixed any import issues found by running
- Ensured error messages are a single line
- Updated relevant documentation if your PR changes user functionality
We follow a convention for commit messages that is designed to answer two questions: what changed and why. The subject line should feature the what and the body of the commit should describe the why.
The format can be described more formally as follows:
[subsystem] <what changed>
<BLANK LINE>
<why this change was made>
<BLANK LINE>
<Footer>
A real world example would look like
[docs] Add the guidelines
The contribution guidelines were not aligned with current practices. Update the
guidelines and reorganize it to bring it up to date.
Follow-up to Id5e7cbb1.
The subject should be no longer than 50 characters, and the body should be no longer than 80 characters. There are some githooks you can install that can help enforce these style requirements.
Once you are done with the pre-PR checklist, push your changes and create a pull request!
When creating your pull request, you should prefix it with the Jira issue, followed by the subsystem name in brackets. It should follow the format
WINC|OCPBUGS-<number>: [<subsystem>] <title>
For example, a docs PR would look like
WINC-959: [docs] reorganizes readme
In doing this, you’ll be linking your PR to the Jira ticket for tracking.
In the case of bug fix PRs, this will also automatically transition the associated Jira bug.
- Opening the PR:
ASSIGNED-->POST - PR merges:
POST-->MODIFIED MODIFIEDto theON_QAtransition will have to be done manually by the PR author.- PR closes without merging, the Jira bug transitions back to NEW status.
If you have no Jira issue or are not a Red Hat employee, your title should simply follow the format [<subsystem>] <title>.
If your work is linked to a GitHub issue, add Fixes #<issue> in the comment.
The WMCO team opens pull requests as drafts before they are reviewed in order to prevent the tests from running right away Open your PR as a draft before requesting reviews.
Once your PR is open, you'll need at least two reviewers te get it merged.
Before moving your PR out of draft, you must have at least one /lgtm and one /approve on the PR. Once you have both, you are free to move it out of draft status by clicking the "ready for review" button in your PR interface. This will let your tests start running, and if they pass, your PR will merge automatically.
If your PR is experiencing a test failure that you believe to be a flake, feel free to run a retest. When retesting, be sure to add a link to the failing test, and a snippet of what caused the failure. The format should be
/retest-required
<explanation of the error>
<reason for retest>
<prow.ci.openshift.org link>
<log snippet of the failure>
Once your tests are passing, and your PR has an approval and a LGTM label, the CI should merge it automatically.
When backporting changes, use the openshift-cherrypick-robot whenever possible to auto-generate backports.
Once your PR has merged, go to the PR and comment /cherry-pick <release> with whatever
supported
releases you want to backport to.
Bugfixes should be backported to all
supported versions.
Once your bugfix is merged, go to the merged PR and comment
/cherry-pick <release>
to trigger the openshift-cherrypick-robot and create an automated backport.
If you have multiple versions you need to backport to, go to each generated backport and run the
/cherry-pick <release> on that instead of master. This ensures the Jira bugs are linked properly.
If for example your PR to master needed to be backported to 4.11, 4.10, and 4.9, you would create an automatic
backport against 4.11, go to that generated backport, and from there run /cherry-pick 4.10. Then, from
your 4.10 backport you would generate a backport for 4.9.
If the cherry pick bot fails, you will have to make your cherry picks manually, and execute /jira cherry-pick OCBUGS- in the manual PR to create the Jira associations.
If any part of the project has bugs or documentation mistakes, please let us know by opening a GitHub issue