Skip to content

Latest commit

 

History

History
155 lines (108 loc) · 7.39 KB

CONTRIBUTING.md

File metadata and controls

155 lines (108 loc) · 7.39 KB
Raw

Contributing

Pull requests for bug fixes are welcome, but before submitting new features or changes to current functionality, open an issue and discuss your ideas or propose the changes you wish to make. After a resolution is reached, a PR can be submitted for review.

Running command in development environment

When developing the tool, it is possible to run commands using yarn launch. It relies on ts-node, so does not require building the project for every new change.

yarn launch synthetics run-tests --config dev/global.config.json

Framework and libraries used

Creating a new command

Follow the Structure below for any commands you add. Then, don't forget the Things to update in the project.

Structure

Commands are stored in the src/commands folder.

The skeleton of a command is composed of a README, an index.ts and a folder for the tests.

src/
└── commands/
    └── fakeCommand/
         ├── __tests__/
         │   └── index.test.ts
         ├── README.md
         └── index.ts

The index.ts file must export classes extending the Command class of clipanion. The commands of all src/commands/*/index.ts files will then be imported and made available in the datadog-ci tool.

A sample index.ts file for a new command would be:

import {Command} from 'clipanion'

export class HelloWorldCommand extends Command {
  public async execute() {
    this.context.stdout.write('Hello world!')
  }
}

module.exports = [HelloWorldCommand]

Lastly, unit tests must be created in the __tests__/ folder. The tests can then be launched with the yarn test command: it finds all files with a filename ending in .test.ts in the repo and executes them.

Beta command

If your command is related to a beta product or feature, or you want to test out the command first, you can mark your command as beta.

To do so, add your command's name to the BETA_COMMANDS array.

Users have to prefix their command line with DD_BETA_COMMANDS_ENABLED=1 to use the command. Make sure to document this in your command's README for visibility. This should be removed once the command goes out of beta.

Optionally, you can create a pre-release for your command by following the Pre-Release Process instructions below.

Things to update

  • The Usage section in the root README must be updated to link to:

    • The new command's README.
    • And 📚 should link to the official Datadog documentation site.
    • Note: If your command is beta, use the Beta commands section instead.

  • The command should be added under the right product in the CODEOWNERS file to ensure the right people are notified when a PR is opened.

    • If you are only adding a sub-command (e.g. datadog-ci <existing-command> <new-sub-command>), no changes are required.

  • If you are adding a command for a new product, you should:

Continuous Integration tests

The CI performs tests to avoid regressions by building the project, running unit tests and running end-to-end tests.

For the end-to-end tests (defined in .github/workflows/ci.yml inside the e2e-test job), the datadog-ci package is installed in a new project with a .tgz artifact and configured with files in the .github/workflows/e2e folder. Then a suite of commands are tested to ensure they work as expected. Each command generally uses a dedicated Datadog org (e.g. Synthetics E2E Testing Org for Synthetics tests).

Workflow

# Compile and watch
yarn watch

# Run the tests
yarn test

# Build code
yarn build

# Make bin executable
yarn prepack

Release Process

Instructions

To release a new version of datadog-ci:

  1. Create a new branch for the version upgrade.
  2. Update the package.json version to X.X.X, commit the change vX.X.X and tag it with git tag vX.X.X.
  3. Push the branch along with the tag with git push --tags origin name-of-the-branch, create a PR, and get at least one approval.
    • Find and open the workflow run corresponding to your tag in this list.
    • Copy the release notes from the summary, and paste them in the description of your PR. This ensures the feature PRs have a link to your release PR.
    • Add the release label to your PR.
    • See this example PR.
  4. Once you've received at least one approval, merge the PR with the "Create a merge commit" strategy.
    • You may notice that a GitHub job is waiting for an approval, and some GitLab jobs are pending: this is expected (see step 6 and 8). You can merge the PR when only those jobs are left.
    • The "Create a merge commit" strategy is required for step 7, and for the GitHub Release to point to an existing commit once the PR is merged.
  5. The npm-publish job is waiting for an approval: accept it and wait for it and its downstream jobs to succeed.
  6. Go to the draft GitHub Release, and publish it as latest.
    • There should be 3 binaries available in the release's assets.
  7. Finally, go to the GitLab pipelines, find the pipeline for your tag, and start the build stage to run the Docker image build jobs.
    • Make sure all the jobs and downstream jobs succeed.

Thanks for creating a release! 🎉

Pre-Release Process

Instructions

To create a pre-release or releasing in a different channel:

  1. Create a new branch for the channel you want to release to (alpha, beta, and more).
  2. Create a PR for your feature branch with the channel branch as a base.
  3. Pick a version following this format: <version>-<channel>. For example, 0.10.9-alpha, 1-beta, and more.
  4. Update the version field in package.json.
  5. Once you've received at least one approval, merge the Pull Request with the "Create a merge commit" strategy.
  6. Create a GitHub Release:
    • Target the channel branch.
    • Pick a tag based on your version <version>-<channel>.
    • Check the This is a pre-release checkbox.
  7. Publish the release and an action publishes it on npm.