This guide provides useful information for contributors.
You may want to test changes you made locally in a cluster. This requires you
to build new container images with the new changes and push them to the
cluster. This process is encapsulated in a Makefile target called
deploy-local
.
Please note this process assumes you have not deployed the operator already. If you have deployed the operator using packages, Helm, or from source, you will need to uninstall the operator before deploying your local changes.
The deploy-local
target needs API access to the cluster. You must
authenticate to the cluster before running deploy-local
using oc login
.
The following command will build images container local changes and push them to the cluster:
$ make deploy-local
This repository contains unit and functional tests for the compliance-operator. Both are invoked using Makefile targets.
Unit tests have no dependency on external systems, or a Kubernetes cluster. You can run them using:
$ make test-unit
The end-to-end tests for the compliance-operator require a Kubernetes deployment. You can also change test and test setup behavior using environment variables when invoking the tests.
For example, you can specify a container registry for content images using
DEFAULT_CONTENT_IMAGE_PATH
and E2E_CONTENT_IMAGE_PATH
. The default registry
for these container images is available on
Quay.
The ComplianceAsCode/content is
built and published to compliance-operator/compliance-operator-content so that
we run end-to-end tests against the latest content images available from
ComplianceAsCode. The content is built using a
Dockerfile
maintained in the ComplianceAsCode/content repository. You may not have a
reason to change these values unless you want to test with different content
images.
$ make e2e
Release notes are maintained in the changelog and follow guidelines based on keep a changelog. This section describes additional guidelines, conventions, and the overall process for writing release notes.
- Each release should contain release notes
- Changes should be applicable to at least one of the six types listed below
- Use literals for code and configuration (e.g.
defaultScanSettingsSchedule
ornodeSelector
) - Write your notes with users as the audience
- Link to additional documentation
- Bug fixes should link to bug reports (GitHub Issues or Jira items)
- Features or enhancements should link to RFEs (GitHub Issues or Jira items)
- Use active voice
- Active voice is more direct and concise than passive voice, perfect for release notes
- Focus on telling the user how a change will affect them
- Examples
- You can now adjust the frequency of your scans by...
- The compliance-operator no longer supports...
The following describe each potential section for a release changelog.
- Enhancements
- Fixes
- Internal Changes
- Deprecations
- Removals
- Security
Enhancements are reserved for communicating any new features or functionality. You should include any new configuration or processes a user needs to take to use the new feature.
Fixes are for noting improvements to any existing functionality.
Internal Changes are ideal for communicating refactors not exposed to end users. Even if a change does not directly impact end users, it is still important to highlight paying down technical debt and the rationale for those changes, especially since they impact the project's roadmap.
Deprecations is for any functionality, feature, or configuration that is being deprecated and staged for removal. Deprecations should include why we're preparing to remove the functionality and signal any suitable replacements users should adopt.
Removals is for any functionality, feature, or configuration that is being removed. Typically, entries in this section will have been deprecated for some period of time. The compliance-operator follows the Kubernetes deprecation policy.
Security is reserved for communicating security fixes and remediations for CVEs.
A change can apply to multiple change types. For example, a bug fix for a CVE should be mentioned in the Fixes and Security sections.
Contributors must include a release note with their changes. New notes should be added to the Unreleased section of the changelog. Reviewers will assess the accuracy of the release note against the change.
Maintainers preparing a new release will propose a change that renames the Unreleased release notes to the newly released version and release date. Maintainers can remove empty sections if it does not contain any release notes for a specific release.
Maintainers will remove the content of the Unreleased section to allow for new release notes for the next release.
Following this process makes it easier to maintain and release accurate release notes without having to retroactively write release notes for merged changes.
The following is an example release note for a feature with a security note.
## Unreleased
### Enhancements
- Allow configuring result servers using `nodeSelector` and `tolerations`
([RFE](https://github.com/openshift/compliance-operator/issues/696))
- You can now specify which nodes to use for storing raw compliance results
using the `nodeSelector` and `tolerations` from `ScanSettings`.
- By default, raw results are stored on nodes labeled
`node-role.kubernetes.io/master`.
- Please refer to the upstream Kubernetes
[documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
for details on how to use `nodeSelector` and `tolerations`.
### Security
- Allow configuring result servers using `nodeSelector` and `tolerations`
([RFE](https://github.com/openshift/compliance-operator/issues/696))
- Raw compliance results may contain sensitive information about the
deployment, its infrastructure, or applications. Make sure you send raw
results to trusted nodes.
The release process is separated into three phases, with dedicated make
targets. All targets require that you supply the OPERATOR_VERSION
prior to
running make
, which should be a semantic version formatted string (e.g.,
OPERATOR_VERSION=0.1.49
).
The first phase of the release process is preparing the release locally. You
can do this by running the make prepare-release
target. All changes are
staged locally. This is intentional so that you have the opportunity to
review the changes before proposing the release in the next step.
The second phase of the release is to push the release to a dedicated branch
against the origin repository. You can perform this step using the make push-release
target.
Please note, this step makes changes to the upstream repository, so it is imperative that you review the changes you're committing prior to this step. This steps also requires that you have necessary permissions on the repository.
The third and final step of the release is to build new images and push them to
an offical image registry. You can build new images and push using make release-images
. Note that this operation also requires you have proper
permissions on the remote registry.