Skip to content

Latest commit

 

History

History
283 lines (217 loc) · 13.2 KB

CONTRIBUTING.md

File metadata and controls

283 lines (217 loc) · 13.2 KB

Contributing to the Conjur OSS Suite

Table of Contents

Prerequisites

Go version

To work in this codebase, you will want to have at least Go v1.17 installed. The code may work on older versions but it has not been tested nor evaluated to be compatible for those configurations. We expect at the very least that you will need Go modules support so you will at minimum need Go v1.11+.

Pull Request Workflow

  1. Search the open issues in GitHub to find out what has been planned
  2. Select an existing issue or open an issue to propose changes or fixes
  3. Add the implementing label to the issue as you begin to work on it
  4. Run tests as described here, ensuring they pass
  5. Submit a pull request, linking the issue in the description (e.g. Connected to #123)
  6. Add the implemented label to the issue, and ask another contributor to review and merge your code

Style guide

Use this guide to maintain consistent style across the project.

Building

Clone https://github.com/cyberark/conjur-oss-suite-release. If you are new to Go, be aware that Go can be very selective about where the files are placed on the filesystem. There is an environment variable called GOPATH, whose default value is ~/go. Conjur OSS Suite uses go modules which require either that you clone this repository outside of your GOPATH or you set the GO111MODULE environment variable to on. We recommend cloning this repository outside of your GOPATH.

Once you've cloned the repository, you can build and/or run the included code.

Running

Usage

  • Edit the file suite.yml as needed
  • Run the CHANGELOG generator:
./parse-changelogs
  • Resulting changelog will be placed in CHANGELOG.md

Advanced usage

The CLI accepts the following arguments/parameters:

  -f string
        Repository YAML file to parse (default "suite.yml")
  -o string
        Output filename
  -p string
        GitHub API token. This can also be passed in as the 'GITHUB_TOKEN' environment variable. The flag takes precedence.
  -r string
        Directory of releases (containinng 'suite_<semver>.yml') files. Set this to empty string to skip suite version diffing. (default "releases")
  -t string
        Output type. Only accepts 'changelog', 'docs-release', 'release', and 'unreleased'. (default "changelog")
  -v string
        Version to embed in the changelog (default "Unreleased")

Testing

Prerequisites

  • Docker

Running all tests

$ go test -v ./...

Note: if you're frequently running the whole test suite during local development, you may want to run the tests after setting the GITHUB_TOKEN env var, so that you won't run up against GitHub API limits.

Alternatively, if you have your GitHub API token saved in your keychain, you may want to use Summon with the Keychain provider and run the test command instead as something like:

summon -p keyring.py \
  --yaml 'GITHUB_TOKEN: !var github/api_token' \
  bash -c 'go test -v ./...'

Running only unit (short) tests

$ go test -v -short ./...

Releasing

Notes on versioning

We version the suite using the syntax 1.x.y+suite.z, where 1.x.y is the version of the Conjur server included in the suite.

This works as follows:

  • When there is sufficient content in the Conjur OSS suite that stakeholders determine a suite release is merited, a new suite release is prepared with version 1.x.y+suite.z, where 1.x.y is the version of Conjur included in the release.

    • Note: suite releases will not necessarily happen for every Conjur core release.

  • If this is the first suite release for Conjur version 1.x.y, then the suite release will be versioned 1.x.y+suite.1, where 1.x.y matches the included Conjur core version.

  • Subsequent suite releases using the same Conjur Open Source version require that the suite version build component be incremented. For example, a second suite release using Conjur 1.2.3 should be versioned 1.2.3+suite.2, as the first one would have been versioned as 1.2.3+suite.1.

Additional notes:

  • If Conjur changes its version with a new minor or patch release, we may have a new suite release, but it is not required unless the stakeholders agree.
  • If Conjur changes its version with a new major release, we must have a new suite release, and stakeholders will determine how long we will continue to support old version of Conjur in the suite.
  • In any Conjur suite release, if the Conjur core version is the same as the last suite release, the .z digit in the suite version will be incremented.
  • If a component in the suite increments its major version, stakeholders will determine when to include the updated component in the suite release.
  • If a component in the suite is being permanently removed, stakeholders will determine when to announce its deprecation in a suite release and will remove it in the next release that follows the deprecation announcement.
  • If a new component is added to the suite, stakeholders will determine when to include the new component in the suite release.
  • Changes to the Conjur server version may result in changes to the suite version in a subsequent release, but changes to the suite version never result in changes to the Conjur server version.

In each line above, when we refer to "stakeholders" we are referring to the maintainers of the components in the suite and CyberArk product management. Anyone can request a new suite release, if they believe it is merited.

Release process

During the suite release kickoff call, we:

  1. Determine the Suite release version

  2. Create a new suite release wiki page

    • Create a new suite release wiki page using the template for this suite release. The title of the page should be the suite release version, e.g. v1.11.7+suite.1, and the new page should be linked to from the suite releases wiki page.

  3. Create a new ZenHub release for this suite release

    • All issues that you open during the kickoff call should be added to this release in ZenHub.

  4. Review components that need releases

    • Review the unreleased changes wiki to determine which components have new tags since the last suite release that should be included in the next release, and which components have unreleased changes to determine whether adding a tag should be included in this suite release process.

      • Note: Entries for components with unreleased changes (changes on the master branch that are not yet available in a GitHub release) show in this report as org/repo @HEAD. The links take you to the commit history for all commits on master that are not included in the latest GitHub release.

    • If there are any components with unreleased changes that should be tagged, open a kind/release issue in that component's repository for adding a new tag. Add the release issue to the ZenHub release and the release wiki page.

  5. Ensure the components have green builds.

    • Check the Jenkins dashboard to make sure there are no ongoing build failures for any of the OSS suite components.

      Note: The Jenkins dashboard does not include the following components at this time:

    • If there are any projects with failing builds that need to be fixed, file a kind/failing-test issue and add the issue to the ZenHub release and the release wiki page.

  6. File a release notes docs issue

    • File an issue in the cyberark/conjur-docs repo to publish the release notes. Review components with updates that will be included in this release to determine whether any additional documentation issues must be completed in this suite release; if there are any, list them in this docs issue.

      Include the release notes doc issue and any other doc issues required for this suite release in the ZenHub release.

After the kickoff meeting, the issues in the ZenHub release must be planned into the regular work stream of the developers and technical writers.

Once the broken build and component release issues have been completed, the PO will:

  1. Update the versions included in the suite release.

    • Edit the suite release config to bump the versions of any components with new tags and/or to add any new components to the next suite release. Also update the CHANGELOG to mark the new version - there's no need to add an entry for the suite version bumps.

    • Submit your changes in a pull request (PR) as per our contributor guidelines.

      • Important: the PR description must include the suite release version (following the versioning standards of the new suite. The maintainers of this project will use this info to complete the release.
      • The PR to modify the suite.yml will automatically kick off the end-to-end tests for the suite against the pinned suite component versions. If the tests don't pass, they'll need to be fixed before the new suite release can be created.
      • To see the status of the automated tests, you can check the status tab in the pull request.

    • Update the PR with draft "What's New" content (in the description or a comment), and tag PM as a reviewer.

    • A maintainer of this project will review the PR to make sure the release is ready to move forward. In particular, they will do the following before approving and merging the PR:

      • Check that the PR description includes the desired suite release version.
      • Check that the PR has been approved by PM.
      • Review the status of the automated tests, to make sure they are passing.
      • Check the Jenkins dashboard to make sure there are no ongoing build failures for any of the OSS suite components.

    • Once the changes to update the suite are approved and merged to master, the maintainer will create a new git tag. Creating a git tag (as outlined in the maintainer docs):

      • Re-runs the automated end-to-end tests against the current pinned versions in suite.yml
      • Auto-generates HTML release notes for the docs website
      • Auto-generates a draft GitHub release; that is, the automated process:
        • Creates the suite CHANGELOG.md
        • Creates GitHub release notes
        • Creates draft GitHub release populated with release notes and with attached artifacts, including CHANGELOG.md, suite.yml, HTML release notes, etc
      • Note: To view the progress of the GitHub actions that automatically run post-tag, you can take a look at this page.
  • The maintainer will copy a ZIP of the HTML release notes output in the draft release to the docs issue linked on the release wiki page.

Once the technical writers have completed and published the documentation, a maintainer will:

  1. Publish the draft GitHub release. If additional validation is needed, it can be initially published as a pre-release and promoted to a full release once final validation is complete.

    Publishing the release:

    • Runs the end-to-end test suite again
    • Archives the current suite.yml as releases/suite-x.y.z.yml where x.y.z is the new suite release version.
    • Manual publishing of the release will make it public for consumers of this repo.