diff --git a/.golangci.yaml b/.golangci.yaml index a65292326..5bcd43568 100644 --- a/.golangci.yaml +++ b/.golangci.yaml @@ -67,7 +67,7 @@ linters-settings: threshold: 150 errcheck: - # report about not checking of errors in type assetions: `a := b.(MyStruct)`; + # report about not checking of errors in type assertions: `a := b.(MyStruct)`; # default is false: such cases aren't reported by default. check-type-assertions: true @@ -176,7 +176,7 @@ linters-settings: unused: # treat code as a program (not a library) and report unused exported identifiers; default is false. # XXX: if you enable this setting, unused will report a lot of false-positives in text editors: - # if it's called for subdir of a project it can't find funcs usages. All text editor integrations + # if it's called for subdirectory of a project it can't find funcs usages. All text editor integrations # with golangci-lint call it on a directory with the changed file. check-exported: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d09036bc..1c5604326 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,22 @@ # Contributing Guidelines -The airshipctl project accepts contributions via gerrit reviews. For help -getting started with gerrit, see the official [OpenDev +The airshipctl project accepts contributions via Gerrit reviews. For help +getting started with Gerrit, see the official [OpenDev documentation](https://docs.openstack.org/contributors/common/setup-gerrit.html). This document outlines the process to help get your contribution accepted. ## Support Channels Whether you are a user or contributor, official support channels are available -[here](https://wiki.openstack.org/wiki/Airship#Get_in_Touch) +[here](https://wiki.openstack.org/wiki/Airship#Get_in_Touch). -You can also report [bugs](https://airship.atlassian.net/issues/?jql=project%20%3D%20AIR%20AND%20issuetype%20%3D%20Bug%20order%20by%20created%20DESC). +You can also report [bugs]( +https://airship.atlassian.net/issues/?jql=project%20%3D%20AIR%20AND%20issuetype%20%3D%20Bug%20order%20by%20created%20DESC). - -Before opening a new issue or submitting a patchset, it's helpful to search the -bug reports above - it's likely that another user has already reported the issue you're -facing, or it's a known issue that we're already aware of. It is also worth -asking on the IRC channels. +Before opening a new issue or submitting a change, it's helpful to search the +bug reports above - it's likely that another user has already reported the +issue you're facing, or it's a known issue that we're already aware of. It is +also worth asking on the IRC channels. ## Story Lifecycle @@ -24,7 +24,7 @@ The airshipctl project uses Jira to track all efforts, whether those are contributions to this repository or other community projects. The Jira issues are a combination of epics, issues, subtasks, bugs, and milestones. We use epics to define large deliverables and many epics have been created already. -The project assumes that developers trying to break down epics into managable +The project assumes that developers trying to break down epics into manageable work will create their own issues/stories and any related subtasks to further breakdown their work. Milestones act as human readable goals for the sprint they are assigned to. @@ -37,6 +37,9 @@ chronologically ordering work in Jira. ### Coding Conventions -Airship has a set of [coding conventions](https://airship-docs.readthedocs.io/en/latest/conventions.html) that are meant to cover all Airship subprojects. +Airship has a set of [coding conventions]( +https://airship-docs.readthedocs.io/en/latest/conventions.html) that are meant +to cover all Airship subprojects. -However, airshipctl also has its own specific coding conventions and standards in the official airshipctl [developer guide](docs/source/developers.md). \ No newline at end of file +However, airshipctl also has its own specific coding conventions and standards +in the official airshipctl [developer guide](docs/source/developers.md). \ No newline at end of file diff --git a/README.md b/README.md index 950d1e6d2..6ca246da4 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ ## What is airshipctl -The `airshipctl` project is a CLI tool and go-lang library for declaratively -managing infrastructure and software. +The `airshipctl` project is a CLI tool and Golang library for declarative +management of infrastructure and software. The goal for the project is to provide a seamless experience to operators -wishing to leverage the best of breed opensource options such as the Cluster +wishing to leverage the best of breed open source options such as the Cluster API, Metal3-io, Kustomize, Kubeadm, and Argo -- into a straight forward and easily approachable tool. @@ -14,10 +14,10 @@ This project is the heart of the effort to produce Airship 2.0, which has three main evolutions from [1.0](https://airshipit.readthedocs.io/projects/airship-docs/en/latest/): -- Expand our use of Entrenched Upstream Projects. +- Expand our use of entrenched upstream projects. - Embrace Kubernetes Custom Resource Definitions (CRD) – Everything becomes an Object in Kubernetes. -- Make the Airship Control Plane Ephemeral. +- Make the Airship control plane ephemeral. To learn more about the Airship 2.0 evolution, please check out the [Airship Blog Series](https://www.airshipit.org/blog/). @@ -42,28 +42,28 @@ In a nutshell, users of `airshipctl` should be able to do the following: 1. Create an `airshipctl` Airship Configuration for their site - sort of like a kubeconfig file. -1. Create a set of declarative documents representing the infrastructure +2. Create a set of declarative documents representing the infrastructure (baremetal, cloud) and software. -1. Run `airshipctl document pull` to clone the document repositories in your +3. Run `airshipctl document pull` to clone the document repositories in your Airship Configuration. -1. When deploying against baremetal infrastructure, run `airshipctl bootstrap +4. When deploying against baremetal infrastructure, run `airshipctl bootstrap isogen` to generate a self-contained ISO that can be used to boot the first host in the cluster into an ephemeral Kubernetes node. -1. When deploying against baremetal infrastructure, run `airshipctl bootstrap +5. When deploying against baremetal infrastructure, run `airshipctl bootstrap remotedirect` to remotely provision the first machine in the cluster using the generated ISO, providing an ephemeral Kubernetes instance that `airshipctl` can communicate with for subsequent steps. This ephemeral host provides a foothold in the target environment so we can follow the standard cluster-api bootstrap flow. -1. Run `airshipctl cluster initinfra --clustertype=ephemeral` to bootstrap the +6. Run `airshipctl cluster initinfra --clustertype=ephemeral` to bootstrap the new ephemeral cluster with enough of the chosen cluster-api provider components to provision the target cluster. -1. Run `airshipctl clusterctl` to use the ephemeral Kubernetes host to provision +7. Run `airshipctl clusterctl` to use the ephemeral Kubernetes host to provision at least one node of the target cluster using the cluster-api bootstrap flow. -1. Run `airshipctl cluster initinfra --clustertype=target` to bootstrap the new +8. Run `airshipctl cluster initinfra --clustertype=target` to bootstrap the new target cluster with any remaining infrastructure necessary to begin running more complex workflows such as Argo. -1. Run `airshipctl workflow submit sitemanage` to run the out of the box sitemanage +9. Run `airshipctl workflow submit sitemanage` to run the out of the box sitemanage workflow, which will leverage Argo to handle bootstrapping the remaining infrastructure as well as deploying and/or updating software. diff --git a/docs/requirements.txt b/docs/requirements.txt index 7a789d9d8..6a6039521 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,14 +4,14 @@ # Documentation sphinx>2.1.0 -oslosphinx>=4.7.0 # Apache-2.0 +oslosphinx>=4.7.0 # Apache-2.0 sphinx_rtd_theme # UML image generation plantuml # Releasenotes -reno>=2.5.0 # Apache-2.0 +reno>=2.5.0 # Apache-2.0 # Sphinx markdown extension recommonmark diff --git a/docs/source/developers.md b/docs/source/developers.md index 2c6aee8df..f8d00c8f9 100644 --- a/docs/source/developers.md +++ b/docs/source/developers.md @@ -17,7 +17,7 @@ We use Make to build our programs. The simplest way to get started is: $ make build ``` -NOTE: The airshipctl application is a go module. This means you do not need to +NOTE: The airshipctl application is a Go module. This means you do not need to clone the repository into `$GOPATH` in order to build it. You should be able to build it from any directory. @@ -75,17 +75,17 @@ We accept changes to the code via Gerrit pull requests. One workflow for doing this is as follows: 1. `git clone` the `opendev.org/airship/airshipctl` repository. -2. Create a new working branch (`git checkout -b feat/my-feature`) and do your - work on that branch. -3. When you are ready for us to review, push your branch to gerrit using - `git-review`. For more information on the gerrit workflow, see the [OpenDev +2. Create a new working branch (`git checkout -b feature/my-feature`) and do your + work on that branch. This will act as your topic in Gerrit. +3. When you are ready for us to review, push your branch to Gerrit using + `git-review`. For more information on the Gerrit workflow, see the [OpenDev documentation]( https://docs.openstack.org/contributors/common/setup-gerrit.html). ### Go Conventions We follow the Go coding style standards very closely. Typically, running `go -fmt` will make your code beautiful for you. +fmt -s -w ./` will make your code beautiful for you. We also typically follow the conventions of `golangci-lint`. diff --git a/docs/source/plugins.md b/docs/source/plugins.md index 62051bf72..a76d3194f 100644 --- a/docs/source/plugins.md +++ b/docs/source/plugins.md @@ -1,10 +1,11 @@ # Plugin Support -##### Table of Contents -* [Compile-In Plugins](#compile-in) -* [Fine Tuning a Build](#fine-tuning) +## Table of Contents + +* [Compile-In Plugins](#compile-in-plugins) +* [Fine Tuning a Build](#fine-tuning-a-build) * [Command Selection](#command-selection) - * [Accessing `airshipctl` settings](#settings) + * [Accessing `airshipctl` settings](#accessing-airshipctl-settings) Our requirements for `airshipctl` contain two very conflicting concepts. One, we'd like to assert that `airshipctl` is a statically linked executable, such @@ -13,12 +14,10 @@ requirements can't coincide within the same project under the standard definition of a plugin. Our solution is to provide a more refined definition of what a plugin actually is. - - ## Compile-In Plugins In order to support plugins to an independent binary file, we use the concept -of *compile-in plugins*. A *compile-in plugin* is an add-on that is built into +of "compile-in plugins". A "compile-in plugin" is an add-on that is built into the main application at compile time, as opposed to runtime. This means that while `airshipctl` is a standalone application, it also acts as a sort of library. In fact, taking a deeper look at `airshipctl` reveals that the base @@ -53,18 +52,28 @@ Usage: airshipctl [command] Available Commands: + bootstrap Bootstrap ephemeral Kubernetes cluster + completion Generate autocompletions script for the specified shell (bash or zsh) + config Modify airshipctl config files + document manages deployment documents help Help about any command + kubectl kubectl controls the Kubernetes cluster manager version Show the version number of airshipctl Flags: - --debug enable verbose output - -h, --help help for airshipctl + --airshipconf string Path to file for airshipctl configuration. (default "$HOME/.airship/config") + --debug enable verbose output + -h, --help help for airshipctl + --kubeconfig string Path to kubeconfig associated with airshipctl configuration. (default "$HOME/.airship/kubeconfig") + +Additional help topics: + airshipctl cluster Control Kubernetes cluster Use "airshipctl [command] --help" for more information about a command. ``` Every other command is treated as a plugin. Changing `main` to the following -adds the default commands, or "plugins", to the`airshipctl` tool: +adds the default commands, or "plugins", to the `airshipctl` tool: ```go func main() { @@ -81,8 +90,12 @@ Compiling and running now provides the following commands: ``` Available Commands: - bootstrap bootstraps airshipctl + bootstrap Bootstrap ephemeral Kubernetes cluster + completion Generate autocompletions script for the specified shell (bash or zsh) + config Modify airshipctl config files + document manages deployment documents help Help about any command + kubectl kubectl controls the Kubernetes cluster manager version Show the version number of airshipctl ------ more commands TBD ------ ``` @@ -124,8 +137,6 @@ func main() { } ``` - - ## Fine Tuning a Build There are a couple of ways in which a plugin author can fine tune their version @@ -133,8 +144,6 @@ of `airshipctl`. These manifest as an ability to pick and choose various plugins (including the defaults), and capabilities for accessing the same settings as other `airshipctl` commands. - - ### Command Selection In the previous section, we introduced the `AddDefaultAirshipCTLCommands` @@ -169,8 +178,6 @@ This can be particularly useful if a plugin author desires to "override" a specific functionality provided by a builtin command. For example, you might write your own `bootstrap` command and use it in place of the builtin. - - ### Accessing `airshipctl` settings The `airshipctl` will contain several settings which may be useful to a plugin diff --git a/docs/source/testing-guidelines.md b/docs/source/testing-guidelines.md index 3e86808ae..63068199d 100644 --- a/docs/source/testing-guidelines.md +++ b/docs/source/testing-guidelines.md @@ -1,6 +1,6 @@ # Testing Guidelines -This document lays out several guidelines to secure high quality and +This document lays out several guidelines to ensure quality and consistency throughout `airshipctl`'s test bed. ## Testing packages @@ -8,6 +8,7 @@ consistency throughout `airshipctl`'s test bed. The `airshipctl` project uses the [testify] library, a thin wrapper around Go's builtin `testing` package. The `testify` package provides the following packages: + * `assert`: Functions from this package can be used to replace most calls to `t.Error` * `require`: Contains the same functions as above, but these functions should @@ -19,7 +20,7 @@ packages: Tests should cover at least __80%__ of the codebase. Anything less will cause the CI gates to fail. A developer should assert that their code meets this -criteria before submitting a patchset. This check can be performed with one of +criteria before submitting a change. This check can be performed with one of the following `make` targets: ``` diff --git a/testutil/utilities.go b/testutil/utilities.go index 1bf5a60b7..d6f5dd3c8 100644 --- a/testutil/utilities.go +++ b/testutil/utilities.go @@ -33,7 +33,7 @@ type CmdTest struct { // and arguments. The initial "airshipctl" is implied CmdLine string - // The instatiated version of the root airshipctl command to test + // The instantiated version of the root airshipctl command to test Cmd *cobra.Command // The expected error