Skip to content

Latest commit

 

History

History
163 lines (96 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

163 lines (96 loc) · 5.43 KB
Raw

Contributing to rhoas CLI

Thank you for contributing to the RHOAS CLI. See below for guides to help you contribute.

Prerequisites

The following will need to be installed on your device in order to contribute to this project.

Development

Running CLI commands

You can run the CLI commands files directly with go run. All commands and subcommands are in the ./pkg/cmd folder.

go run ./cmd/rhoas kafka create "test" --provider=aws --region=us-east-1

Connecting to stage env instead of production

To use QA environment we need to login using following arguments

rhoas login --api-gateway=stage --mas-auth-url=stage

Development features

To enable development and early access commands please set environment variable in your terminal:

export RHOAS_DEV=true
rhoas service-registry

To permamently enable dev commands add export to your bash/zsh profile files

export RHOAS_DEV=true

Development commands

make lint

Runs a linter on the Go source code. Configuration can be found in .golangci.yaml. There are a number of lint rules enabled. You can find a full list of rules here with usage and configuration guides.

make install

Builds a binary in the $GOPATH/bin directory. Can be executed globally as it is in your $PATH.

make binary

Builds an executable binary rhoas of the CLI in the project root. Executable only inside the workspace.

make format

Formats source code.

make generate

Generates code based on comments in code. This is primarily used to generate interface stubs using moq.

Testing

If you have the Go extension for VS Code, you can generate test stubs for a file, package or function. See Go#Test

make test/unit

Runs unit tests

Using CLI with Mock RHOAS API

RHOAS SDK provides mock for all supported APIs. To use mock you need to have NPM installed on your system and have free port 8000 To work and test CLI locally please follow the mock readme and then login into cli using dev profile:

rhoas login --api-gateway=http://localhost:8000

make mock-api/start

Starts the mock all services Manager API and Instance API at http://localhost:8000.

Logging in

To log in to the mock API, run rhoas login against the local server with your authentication token:

rhoas login --api-gateway=http://localhost:8000

Internationalization

All text strings are placed in ./pkg/localize/locales directory.

Documentation

The main CLI documentation source files are stored in the ./pkg/localize/locales/en/cmd/ directory.

The CLI documentation output is generated in the ./docs directory.

Generating documentation

Documentation can be generated from the CLI commands.

make docs/generate

make docs/generate

After running the command, the documentation should be generated in AsciiDoc format.

make docs/generate-modular-docs

After running the command, the dist directory will contain the documentation conforming to the modular docs specification.

Best practices

Releases

This project follows Semantic Versioning. Before creating a release, identify if it will be a major, minor, or patch release. In the following example, we will create a patch release 0.20.1.

NOTE: When creating a release it is good practice to create a pre-release first to monitor the integration tests to ensure everything works as it should.

Create snapshot

For testing purposes we should always release a local snapshot version for testing (requires GoReleaser)

goreleaser --snapshot --rm-dist

Creating the release

Execute git tag v0.20.1 to create the release tag. Then execute git push origin v0.20.1 to push to the tag to your remote (GitHub). Once pushed, a GitHub Action will create a release on GitHub and upload the binaries.

NOTE: To create a pre-release, the tag should have appropriate suffix, e.g v0.20.1-alpha1

Generate a changelog

NOTE: This step is not required for pre-releases.

git-chglog is used to generate a changelog for the current release.

Run ./scripts/generate-changelog.sh to output the changes between the current and last stable releases. Paste the output into the description of the release on GitHub.