diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..95ff9bb5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,141 @@ +# Contribute to the STACKIT CLI + +Your contribution is welcome! Thank you for your interest in contributing to the STACKIT CLI. We greatly value your feedback, feature requests, additions to the code, bug reports or documentation extensions. + +## Table of contents + +- [Developer Guide](#developer-guide) +- [Useful Make commands](#useful-make-commands) +- [Repository structure](#repository-structure) +- [Implementing a new command](#implementing-a-new-command) + - [Command file structure](#command-file-structure) + - [Outputs, prints and debug logs](#outputs-prints-and-debug-logs) +- [Onboarding a new STACKIT service](#onboarding-a-new-stackit-service) +- [Local development](#local-development) +- [Code Contributions](#code-contributions) +- [Bug Reports](#bug-reports) + +## Developer Guide + +Prerequisites: + +- [`Go`](https://go.dev/doc/install) 1.24+ +- [`yamllint`](https://yamllint.readthedocs.io/en/stable/quickstart.html) + +### Useful Make commands + +These commands can be executed from the project root: + +- `make build`: compile the CLI and save the binary under _./bin/stackit_ +- `make lint`: lint the code +- `make generate-docs`: generate Markdown documentation for every command +- `make test`: run unit tests +- `make coverage`: create unit test coverage report (output file: `coverage.html`) + +### Repository structure + +The CLI commands are located under `internal/cmd`, where each folder includes the source code for each subcommand (including their own subcommands). Inside `pkg` you can find several useful packages that are shared by the commands and provide additional functionality such as `flags`, `globalflags`, `tables`, etc. + +### Implementing a new command + +Let's suppose you want to implement a new command `bar`, that would be the direct child of an existing command `stackit foo` (meaning it would be invoked as `stackit foo bar`): + +1. You would start by creating a new folder `bar/` inside `internal/cmd/foo/` +2. Following with the creation of a file `bar.go` inside your new folder `internal/cmd/foo/bar/` + 1. The Go package should be similar to the command usage, in this case `package bar` would be an adequate name + 2. Please refer to the [Command file structure](./CONTRIBUTING.md/#command-file-structure) section for details on the structure of the file itself +3. To register the command `bar` as a child of the existing command `foo`, add `cmd.AddCommand(bar.NewCmd(p))` to the `addSubcommands` method of the constructor of the `foo` command + 1. In this case, `p` is the `printer` that is passed from the root command to all subcommands of the tree (refer to the [Outputs, prints and debug logs](./CONTRIBUTING.md/#outputs-prints-and-debug-logs) section for more details regarding the `printer`) + +Please remember to run `make generate-docs` after your changes to keep the commands' documentation updated. + +#### Command file structure + +Below is a typical structure of a CLI command: + +https://github.com/stackitcloud/stackit-cli/blob/main/.github/docs/contribution-guide/cmd.go + +Please remember to always add unit tests for `parseInput`, `buildRequest` (in `bar_test.go`), and any other util functions used. + +If the new command `bar` is the first command in the CLI using a STACKIT service `foo`, please refer to [Onboarding a new STACKIT service](./CONTRIBUTING.md/#onboarding-a-new-stackit-service). + +You may also have to register the `bar` command as a new sub-command: + +https://github.com/stackitcloud/stackit-cli/blob/a5438f4cac3a794cb95d04891a83252aa9ae1f1e/internal/cmd/root.go#L162-L195 + +#### Outputs, prints and debug logs + +The CLI has 4 different verbosity levels: + +- `error`: For only displaying errors +- `warning`: For displaying user facing warnings _(and all of the above)_ +- `info` (default): For displaying user facing info, such as operation success messages and spinners _(and all of the above)_ +- `debug`: For displaying structured logs with different levels, including errors _(and all of the above)_ + +For prints that are specific to a certain log level, you can use the methods defined in the `print` package: `Error`, `Warn`, `Info`, and `Debug`. + +For command outputs that should always be displayed, no matter the defined verbosity, you should use the `print` methods `Outputf` and `Outputln`. These should only be used for the actual output of the commands, which can usually be described by "I ran the command to see _this_". + +#### Handling secrets + +If your command needs secrets as input, please make sure to use `flags.SecretFlag()` and `flags.SecretFlagToStringPointer()`. +These functions implement reading from stdin or a file. + +They also support reading the secret value as a command line argument (deprecated, marked for removal in Oct 2026). + +### Onboarding a new STACKIT service + +If you want to add a command that uses a STACKIT service `foo` that was not yet used by the CLI, you will first need to implement a few extra steps to configure the new service: + +1. Add a `FooCustomEndpointKey` key in `internal/pkg/config/config.go` (and add it to `ConfigKeys` and set the to default to `""` using `viper.SetDefault`) +2. Update the `stackit config unset` and `stackit config unset` commands by adding flags to set and unset a custom endpoint for the `foo` service API, respectively, and update their unit tests +3. Set up the SDK client configuration, using the authentication method configured in the CLI + + 1. This is done in `internal/pkg/services/foo/client/client.go` + 2. Below is an example of a typical `client.go` file structure: + +https://github.com/stackitcloud/stackit-cli/blob/main/.github/docs/contribution-guide/client.go + +### Local development + +To test your changes, you can either: + +1. Build the application locally by running: + + ```bash + $ go build -o ./bin/stackit + ``` + + To use the application from the root of the repository, you can run: + + ```bash + $ ./bin/stackit [group] [subgroup] [command] [flags] + ``` + +2. Skip building and run the Go application directly using: + + ```bash + $ go run . [group] [subgroup] [command] [flags] + ``` + +## Code Contributions + +To make your contribution, follow these steps: + +1. Check open or recently closed [Pull Requests](https://github.com/stackitcloud/stackit-cli/pulls) and [Issues](https://github.com/stackitcloud/stackit-cli/issues) to make sure the contribution you are making has not been already tackled by someone else. +2. Fork the repo. +3. Make your changes in a branch that is up-to-date with the original repo's `main` branch. +4. Commit your changes including a descriptive message +5. Create a pull request with your changes. +6. The pull request will be reviewed by the repo maintainers. If you need to make further changes, make additional commits to keep commit history. When the PR is merged, commits will be squashed. + +## Bug Reports + +If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/stackit-cli/issues/new). + +To ensure we can provide the best support to your issue, follow these guidelines: + +1. Go through the existing issues to check if your issue has already been reported. +2. Make sure you are using the latest version of the STACKIT CLI, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug. +3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the CLI, which operating system you are using and the corresponding version. +4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient. diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md index 0c1363917..409323c79 100644 --- a/CONTRIBUTION.md +++ b/CONTRIBUTION.md @@ -1,141 +1,6 @@ -# Contribute to the STACKIT CLI +# Moved -Your contribution is welcome! Thank you for your interest in contributing to the STACKIT CLI. We greatly value your feedback, feature requests, additions to the code, bug reports or documentation extensions. +Our contribution guide has moved to [CONTRIBUTING.md](./CONTRIBUTING.md). -## Table of contents +This way we stick to GitHub's standards: [Setting guidelines for repository contributors](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). -- [Developer Guide](#developer-guide) -- [Useful Make commands](#useful-make-commands) -- [Repository structure](#repository-structure) -- [Implementing a new command](#implementing-a-new-command) - - [Command file structure](#command-file-structure) - - [Outputs, prints and debug logs](#outputs-prints-and-debug-logs) -- [Onboarding a new STACKIT service](#onboarding-a-new-stackit-service) -- [Local development](#local-development) -- [Code Contributions](#code-contributions) -- [Bug Reports](#bug-reports) - -## Developer Guide - -Prerequisites: - -- [`Go`](https://go.dev/doc/install) 1.24+ -- [`yamllint`](https://yamllint.readthedocs.io/en/stable/quickstart.html) - -### Useful Make commands - -These commands can be executed from the project root: - -- `make build`: compile the CLI and save the binary under _./bin/stackit_ -- `make lint`: lint the code -- `make generate-docs`: generate Markdown documentation for every command -- `make test`: run unit tests -- `make coverage`: create unit test coverage report (output file: `coverage.html`) - -### Repository structure - -The CLI commands are located under `internal/cmd`, where each folder includes the source code for each subcommand (including their own subcommands). Inside `pkg` you can find several useful packages that are shared by the commands and provide additional functionality such as `flags`, `globalflags`, `tables`, etc. - -### Implementing a new command - -Let's suppose you want to implement a new command `bar`, that would be the direct child of an existing command `stackit foo` (meaning it would be invoked as `stackit foo bar`): - -1. You would start by creating a new folder `bar/` inside `internal/cmd/foo/` -2. Following with the creation of a file `bar.go` inside your new folder `internal/cmd/foo/bar/` - 1. The Go package should be similar to the command usage, in this case `package bar` would be an adequate name - 2. Please refer to the [Command file structure](./CONTRIBUTION.md/#command-file-structure) section for details on the structure of the file itself -3. To register the command `bar` as a child of the existing command `foo`, add `cmd.AddCommand(bar.NewCmd(p))` to the `addSubcommands` method of the constructor of the `foo` command - 1. In this case, `p` is the `printer` that is passed from the root command to all subcommands of the tree (refer to the [Outputs, prints and debug logs](./CONTRIBUTION.md/#outputs-prints-and-debug-logs) section for more details regarding the `printer`) - -Please remember to run `make generate-docs` after your changes to keep the commands' documentation updated. - -#### Command file structure - -Below is a typical structure of a CLI command: - -https://github.com/stackitcloud/stackit-cli/blob/main/.github/docs/contribution-guide/cmd.go - -Please remember to always add unit tests for `parseInput`, `buildRequest` (in `bar_test.go`), and any other util functions used. - -If the new command `bar` is the first command in the CLI using a STACKIT service `foo`, please refer to [Onboarding a new STACKIT service](./CONTRIBUTION.md/#onboarding-a-new-stackit-service). - -You may also have to register the `bar` command as a new sub-command: - -https://github.com/stackitcloud/stackit-cli/blob/a5438f4cac3a794cb95d04891a83252aa9ae1f1e/internal/cmd/root.go#L162-L195 - -#### Outputs, prints and debug logs - -The CLI has 4 different verbosity levels: - -- `error`: For only displaying errors -- `warning`: For displaying user facing warnings _(and all of the above)_ -- `info` (default): For displaying user facing info, such as operation success messages and spinners _(and all of the above)_ -- `debug`: For displaying structured logs with different levels, including errors _(and all of the above)_ - -For prints that are specific to a certain log level, you can use the methods defined in the `print` package: `Error`, `Warn`, `Info`, and `Debug`. - -For command outputs that should always be displayed, no matter the defined verbosity, you should use the `print` methods `Outputf` and `Outputln`. These should only be used for the actual output of the commands, which can usually be described by "I ran the command to see _this_". - -#### Handling secrets - -If your command needs secrets as input, please make sure to use `flags.SecretFlag()` and `flags.SecretFlagToStringPointer()`. -These functions implement reading from stdin or a file. - -They also support reading the secret value as a command line argument (deprecated, marked for removal in Oct 2026). - -### Onboarding a new STACKIT service - -If you want to add a command that uses a STACKIT service `foo` that was not yet used by the CLI, you will first need to implement a few extra steps to configure the new service: - -1. Add a `FooCustomEndpointKey` key in `internal/pkg/config/config.go` (and add it to `ConfigKeys` and set the to default to `""` using `viper.SetDefault`) -2. Update the `stackit config unset` and `stackit config unset` commands by adding flags to set and unset a custom endpoint for the `foo` service API, respectively, and update their unit tests -3. Set up the SDK client configuration, using the authentication method configured in the CLI - - 1. This is done in `internal/pkg/services/foo/client/client.go` - 2. Below is an example of a typical `client.go` file structure: - -https://github.com/stackitcloud/stackit-cli/blob/main/.github/docs/contribution-guide/client.go - -### Local development - -To test your changes, you can either: - -1. Build the application locally by running: - - ```bash - $ go build -o ./bin/stackit - ``` - - To use the application from the root of the repository, you can run: - - ```bash - $ ./bin/stackit [group] [subgroup] [command] [flags] - ``` - -2. Skip building and run the Go application directly using: - - ```bash - $ go run . [group] [subgroup] [command] [flags] - ``` - -## Code Contributions - -To make your contribution, follow these steps: - -1. Check open or recently closed [Pull Requests](https://github.com/stackitcloud/stackit-cli/pulls) and [Issues](https://github.com/stackitcloud/stackit-cli/issues) to make sure the contribution you are making has not been already tackled by someone else. -2. Fork the repo. -3. Make your changes in a branch that is up-to-date with the original repo's `main` branch. -4. Commit your changes including a descriptive message -5. Create a pull request with your changes. -6. The pull request will be reviewed by the repo maintainers. If you need to make further changes, make additional commits to keep commit history. When the PR is merged, commits will be squashed. - -## Bug Reports - -If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/stackit-cli/issues/new). - -To ensure we can provide the best support to your issue, follow these guidelines: - -1. Go through the existing issues to check if your issue has already been reported. -2. Make sure you are using the latest version of the STACKIT CLI, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug. -3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the CLI, which operating system you are using and the corresponding version. -4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient. diff --git a/README.md b/README.md index 579b9a4d1..80e5aee38 100644 --- a/README.md +++ b/README.md @@ -192,7 +192,7 @@ If you encounter any issues or have suggestions for improvements, please open an ## Contribute -Your contribution is welcome! For more details on how to contribute, refer to our [contribution guide](./CONTRIBUTION.md). +Your contribution is welcome! For more details on how to contribute, refer to our [contribution guide](./CONTRIBUTING.md). ## Release creation