The om
project team welcomes contributions from the community. If you wish to contribute code and you have not signed our contributor license agreement, our bot will update the issue when you open a Pull Request. For any questions about the CLA process, please refer to our FAQ.
In all cases, following this workflow will help all contributors to om
to
participate more equitably:
- Search existing github issues that may already describe the idea you have. If you find one, consider adding a comment that adds additional context about your use case, the exact problem you need solved and why, and/or your interest in helping to contribute to that effort.
- If there is no existing issue that covers your idea, open a new issue to
describe the change you would like to see in
om
. Please provide as much context as you can about your use case, the exact problem you need solved and why, and the reason why you would like to see this change. If you are reporting a bug, please include steps to reproduce the issue if possible. - Any number of folks from the community may comment on your issue and ask
additional questions. A maintainer will add the
pr welcome
label to the issue when it has been determined that the change will be welcome. Anyone from the community may step in to make that change. - If you intend to make the changes, comment on the issue to indicate your interest in working on it to reduce the likelihood that more than one person starts to work on it independently.
First things first. Just clone the repo and run the tests to make sure you're ready to safely start exploring or adding new features.
git clone https://github.com/pivotal-cf/om
om
should NOT be cloned to your GOPATH
.
We recommend running tests through our docker image to ensure that the tests run in a consistent environment.
Here's a one-liner to run the tests:
docker run \
-it \
-v $(pwd):/workspace \
-w /workspace internalpcfplatformautomation/ci:testing \
/bin/bash \
-c "go install github.com/onsi/ginkgo/v2/ginkgo && CGO_ENABLED=1 ginkgo -r -race -succinct -randomizeAllSpecs -randomizeSuites -keepGoing -skipPackage acceptance,vmlifecyclecommands,vmmanagers"
This follows the setup that we use in our CI pipeline.
Our vendoring tool of choice at present is go modules which is rapidly becoming the standard.
Adding a dependency is relatively straightforward (first make sure you have the dep binary):
go get github.com/some-user/some-dep
Check in both the manifest changes and the file additions in the vendor directory.
If you need to generate a new fake for a PR, you will need to
go get github.com/maxbrunsfeld/counterfeiter
.
Counterfeiter needs to be pinned to commit f7bde7cbdb1288611466a0d715b1bbc956519eb1
To generate fakes for all files in a directory, run go generate ./...
Much of om
's documentation is automatically generated.
If you make any changes to any of the task flags, or need to elaborate on how to use a new feature,
be sure to run docsgenerator
before submitting your PR.
NOTE: With any significant change in behavior to om
that should be noted in
the next release's release notes, you should also add a note to CHANGELOG.md.
- When you have a set of changes to contribute back to
om
, create a pull request (PR) and reference the issue that the changes in the PR are addressing. NOTE: maintainers ofom
with commit access may commit directly toom
instead of creating a pull request. Alternatively, they may choose to create a pull request for greater visibility around a set of changes. There is no black and white rule here for maintainer. Use your judgement. - The code in your pull request will be automatically tested in our continuous integration pipeline. At this time, we cannot expose all the logs for this pipeline, but we may do so in the future if we can determine it is safe and unlikely to lead to any exposure of sensitive information.
- Your pull request will be reviewed by one or more maintainers. You may also receive feedback from others in the community. The feedback may come in the form of requests for additional changes to meet expectations for code quality, consistency or test coverage. Or it could be clarifying questions to better understand the decisions you made in your implementation.
- When a maintainer accepts your changes, they will merge your pull request. If there are outstanding requests for changes or other small changes they feel can be made to improve the changed code, they may make additional changes or merge the changes manually. It's always nice to have changes come in just as the team would like to see them, but we'll try not to hold up a pull request for a long period of time due to minor changes.
NOTE: With any significant change in behavior to om
that should be noted in
the next release's release notes, you should also add a note to CHANGELOG.md.
- a small sharp tool for fast, reliable interaction with the Operations Manager API via the command line, and specific external tasks for bettering the experience with interaction with the Operations Manager API
- enable humans easily interact with Operations Manager via the command line
- enable scripts and continuous integration systems to programmatically interact with Operations Manager
- single binary that can be run on multiple platforms without additional dependencies
- a consistent, tested code base that welcomes contributions from the community
- idempotency for all commands
Maintaining complete parity with the features that the Operations Manager API supports is not an explicit design goal, but we welcome any ideas for new features that may become feasible as new features are made available in the API.
In general, features are driven by acceptance and unit tests. Acceptance tests execute the compiled binary and exercise the feature including user facing errors. Unit tests document and specify the behavior of smaller components that make up that feature. Take a look at the code around and be consistent. Feel free to ask questions along the way or to create a pull request early to get feedback on code that is a work in progress.
At this time, there is no official process for becoming a comitter to om
. The
project is currently maintained by the TAS Operability team. But we're open to new ideas here!
om
was intially developed to be a less flakey / faster replacement of opsmgr
Please summarize your changes in CHANGELOG.yml. Explain the problem you solved, what command(s) were affected, and what issue the PR is addressing.
Thank you for being an om
contributor!