Skip to content

Latest commit

 

History

History
153 lines (104 loc) · 9.15 KB

CONTRIBUTING.md

File metadata and controls

153 lines (104 loc) · 9.15 KB
Raw

Contributing to MongoDB CLI

Thanks for your interest in contributing to MongoDB Atlas CLI and MongoDB CLI, this document describes some guidelines necessary to participate in the community.

Table of Contents

Asking Support Questions

MongoDB support is provided under MongoDB Atlas or Enterprise Advance support plans. Please don't use the GitHub issue tracker to ask questions.

Feature Requests

We welcome any feedback or feature request, to submit yours please head over to our feedback page.

Reporting Issues

Please create a GitHub issue describing the kind of problem you're facing with as much detail as possible, including things like operating system or anything else may be relevant to the issue.

Auto-close Stale Issues and Pull Requests

  • After 30 days of no activity (no comments or commits on an issue/PR) we automatically tag it as "stale" and add a message: This issue/PR has gone 30 days without any activity and meets the project's definition of "stale". This will be auto-closed if there is no new activity over the next 60 days. If the issue is still relevant and active, you can simply comment with a "bump" to keep it open, or add the label "not_stale". Thanks for keeping our repository healthy!
  • After 60 more days of no activity we automatically close the issue/PR.

Submitting Patches

The Atlas CLI project welcomes all contributors and contributions regardless of skill or experience level. If you are interested in helping with the project, please follow our guidelines.

Code Contribution Guidelines

To create the best possible product for our users and the best contribution experience for our developers, we have a set of guidelines to ensure that all contributions are acceptable.

To make the contribution process as seamless as possible, we ask for the following:

  • Fork the repository to work on your changes. Note that code contributions are accepted through pull requests to encourage discussion and allow for a smooth review experience.
  • When you’re ready to create a pull request, be sure to:
    • Sign the CLA.
    • Have test cases for the new code. If you have questions about how to do this, please ask in your pull request or check the Building and Testing section.
    • Run make fmt.
    • Add documentation if you are adding new features or changing functionality.
    • Confirm that make check succeeds. GitHub Actions.

Development Setup

Prerequisite Tools

Environment

  • Fork the repository.
  • Clone your forked repository locally.
  • We use Go Modules to manage dependencies, so you can develop outside your $GOPATH.
  • We use golangci-lint to lint our code, you can install it locally via make setup.

Building and Testing

The following is a short list of commands that can be run in the root of the project directory

  • Run make see a list of available targets.
  • Run make test to run all unit tests.
  • Run make lint to validate against our linting rules.
  • Run E2E_TAGS=e2e,atlas make e2e-test will run end to end tests against an Atlas instance, please make sure to have set MCLI_* variables pointing to that instance.
  • Run E2E_TAGS=cloudmanager,remote,generic make e2e-test will run end-to-end tests against a Cloud Manager instance.
    Please remember to: (a) have a running automation agent, and (b) set MCLI_* variables to point to your Cloud Manager instance.
  • Run make build to generate a local binary in the ./bin folder.

We provide a git pre-commit hook to format and check the code, to install it run make link-git-hooks.

Generating Mocks

We use mockgen to handle mocking in our unit tests. If you need a new mock please update or add the //go:generate instruction to the appropriate file.

API Interactions

Atlas CLI and MongoDB CLI use go-client-mongodb-atlas and o-client-mongodb-ops-manager to interact with Atlas or Ops Manager/CLoud Manager Any new feature should first update the respective client.

Adding a New Command

atlascli and mongocli use Cobra as a framework for defining commands, in addition to this we have defined a basic structure that should be followed. For a mongocli scope newCommand command, a file internal/cli/scope/new_command.go should implement:

  • A ScopeNewCommandOpts struct which handles the different options for the command.
  • At least a func (opts *ScopeNewCommandOpts) Run() error function with the main command logic.
  • A func ScopeNewCommandBuilder() *cobra.Command function to put together the expected cobra definition along with the ScopeNewCommandOpts logic.
  • A set of documentation fields further described in the section below.

Commands follow a RESTful approach to match the APIs, whenever possible. For that reason, command arguments tend to match the path and query params of the APIs, with the last param being a required argument and the rest handled via flag options. For commands that create or modify complex data structures, the use of configuration files is preferred over flag options.

How to define flags:

Flags are a way to modify the command, also may be called "options". Flags always have a long version with two dashes (--state) but may also have a shortcut with one dash and one letter (-s).

atlascli uses the following types of flags:

  • --flagName value: this type of flag passes the value to the command. Examples: --projectId 5efda6aea3f2ed2e7dd6ce05
  • --booleanFlag: this flag represents a boolean and it sets the related variable to true when the flag is used, false otherwise. Example: --force
  • --flagName value1,value2,..,valueN: you will also find flags that accept a list of values. This type of flag can be very useful to represent data structures as --role roleName1@db,roleName2@db, --privilege [email protected],[email protected], or --key field:type. As shown in the examples, the standard format used to represent data structures consists of splitting the first value with the second one by at sign @ or colon :, and the second value with the third one by a full stop .. We recommend using configuration files for complex data structures that require more than three values. For an example of configuration files, see mongocli atlas cluster create.

Documentation Requirements

If you are adding a brand-new command, or updating a command that has no doc annotations, please define the following doc structures for the command. For more information on all command structs, see Cobra.

  • Add Use - (Required) Shows the command and arguments if applicable. Will show up in 'help' output.
  • Add Short - (Required) Briefly describes the command. Will show up in 'help' output.
  • Add Example - (Required) Example of how to use the command. Will show up in 'help' output.
  • Add Annotations - If the command has arguments, annotations should be added. They consist of key/value pairs that describe arguments in the command and are added to the generated documentation.
  • Add Long - Fully describes the command. Will show up in 'help' output.

Furthermore, after adding the necessary structure, ensure that applicable documentation is generated by running make gen-docs.

  • Run make gen-docs- This generates the documentation for the introduced command.
  • Review the PR with the doc team.

Third Party Dependencies

We scan our dependencies for vulnerabilities and incompatible licenses using Snyk. To run Snyk locally please follow their CLI reference.

Maintainer's Guide

Reviewers, please ensure that the CLA has been signed by referring to the contributors tool (internal link).

For changes that involve user facing copy please include docs-cloud-team as a reviewer.