CLOUDP-297209: Add disclaimer to --help and docs

[jeroenvervaeke]

Proposed changes

Add "experimental: " to every API command to:

• --help
• docs

Jira ticket: CLOUDP-297209

@mongodb/docs-cloud-team I changed these things:

• Added a description for atlas api
• Added experimental: to every command

I decided to use the help template to not overload the help text for subcommand:

❯ ./bin/atlas api clusters --help
experimental: Returns, adds, edits, and removes database deployments. Changes to cluster configurations can affect costs. This resource requires your Project ID.

Usage:
  atlas api clusters [command]

Available Commands:
  createCluster                      Creates one cluster in the specified project.
  deleteCluster                      Removes one cluster from the specified project.
  ...
  upgradeSharedClusterToServerless   Upgrades a shared-tier cluster to a serverless instance in the specified project.

Flags:
  -h, --help   help for clusters

Global Flags:
  -P, --profile string   Name of the profile to use from your configuration file. To learn about profiles for the Atlas CLI, see https://dochub.mongodb.org/core/atlas-cli-save-connection-settings.

Use "atlas api clusters [command] --help" for more information about a command.

But then on ./bin/atlas api clusters createCluster --help

❯ ./bin/atlas api clusters createCluster --help
experimental: Creates one cluster in the specified project. Clusters contain a group of hosts that maintain the same data set. This resource can create clusters with asymmetrically-sized shards. Each project supports up to 25 database deployments. To use this resource, the requesting API Key must have the Project Owner role. This feature is not available for serverless clusters. This command is invoking the endpoint with OperationID: 'createCluster'. For more information about flags, format of --file and examples, see: https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Clusters/operation/createCluster

Usage:
  atlas api clusters createCluster [flags]

Flags:
      --envelope             flag that indicates whether Application wraps the response in an envelope JSON object
      --file string          path to the file which contains the api request contents
      --groupId string       unique 24-hexadecimal digit string that identifies your project
  -h, --help                 help for createCluster
      --output string        preferred api format, can be ["json", go-template] (default "json")
      --output-file string   file to write the api output to. This flag is required when the output of an endpoint is binary (ex: gzip) and the command is not piped (ex: atlas command > out.zip)
      --pretty               flag that indicates whether the response body should be in the prettyprint format
      --version string       api version to use when calling the api call [options: "2023-01-01", "2023-02-01", "2024-08-05", "2024-10-23"], defaults to the latest version or the profiles api_version config value if set (default "2024-10-23")

Global Flags:
  -P, --profile string   Name of the profile to use from your configuration file. To learn about profiles for the Atlas CLI, see https://dochub.mongodb.org/core/atlas-cli-save-connection-settings.

[fmenezes]

nit: personally I would not change the help template but rather I'd change the command go template

[jwilliams-mongo]

@jeroenvervaeke For the docs I think users might be confused by the experimental tag. Can we elaborate? Perhaps mentioning why these are experimental would help inform folks and prevent questions. I think changing it from experimental to a complete sentence that describes support or usage implications would do the trick.

[jeroenvervaeke]

@jeroenvervaeke For the docs I think users might be confused by the experimental tag. Can we elaborate? Perhaps mentioning why these are experimental would help inform folks and prevent questions. I think changing it from experimental to a complete sentence that describes support or usage implications would do the trick.

Thanks for the suggestions on slack.
I've added a link to the atlas api docs, as discussed. (The link is not published yet, so you'll get a 404 right now)

[apix-bot]

Coverage Report 📈

Branch	Commit	Coverage
auto-generation	037acf6	39.0%
CLOUDP-297209	e194dc3	39.1%
	Difference	.1%