From 2d26d2e6c6dc50d2c232f09138699c9574ee27fc Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Sun, 17 Jun 2018 18:57:39 -0700 Subject: [PATCH] Implement new readme generator (#61) --- .travis.yml | 1 + Makefile | 6 + README.md | 278 ++++++++++++++++++++++---------------- README.yaml | 108 +++++++++++++++ docs/targets.md | 78 +++++++++++ modules/docs/Makefile | 14 ++ modules/packages/Makefile | 10 +- modules/readme/Makefile | 35 +++-- modules/template/Makefile | 2 +- templates/README.md | 162 ++++++++++++++++++++-- 10 files changed, 557 insertions(+), 137 deletions(-) create mode 100644 README.yaml create mode 100644 docs/targets.md create mode 100644 modules/docs/Makefile diff --git a/.travis.yml b/.travis.yml index 0bab7391..8bcad3cd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,6 +17,7 @@ install: - make docker/login - make go/deps-build - make go/deps-dev +- make readme/deps script: - make bash/lint diff --git a/Makefile b/Makefile index ebbcadff..f06f14b2 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,9 @@ export SELF ?= make export PATH := $(BUILD_HARNESS_PATH)/vendor:$(PATH) export DOCKER_BUILD_FLAGS ?= +# List of targets the `readme` target should call before generating the readme +export README_DEPS ?= docs/targets.md + # Import Makefiles into current context include $(BUILD_HARNESS_PATH)/Makefile.* include $(BUILD_HARNESS_PATH)/modules/*/bootstrap.Makefile* @@ -13,3 +16,6 @@ ifndef TRANSLATE_COLON_NOTATION %: @$(SELF) $(subst :,/,$@) TRANSLATE_COLON_NOTATION=false endif + + + diff --git a/README.md b/README.md index af2b9229..b3f1d2e2 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,18 @@ -# Cloud Posse Build Harness [![Build Status](https://travis-ci.org/cloudposse/build-harness.svg)](https://travis-ci.org/cloudposse/build-harness) - + + +[![Cloud Posse](https://cloudposse.com/logo-300x69.png)](https://cloudposse.com) + +# Build Harness [![Build Status](https://travis-ci.org/cloudposse/build-harness.svg?branch=master)](https://travis-ci.org/cloudposse/build-harness) [![Latest Release](https://img.shields.io/github/release/cloudposse/build-harness.svg)](https://github.com/cloudposse/build-harness/releases) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com) + This `build-harness` is a collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more. +It's designed to work with CI/CD systems such as Travis CI, CircleCI and Jenkins.This project is part of our comprehensive ["SweetOps"](https://docs.cloudposse.com) approach towards DevOps. -It's designed to work with CI/CD systems such as Travis CI, CircleCI and Jenkins. It's 100% Open Source and licensed under [APACHE2](LICENSE). + ## Usage At the top of your `Makefile` add, the following... @@ -25,91 +27,137 @@ This automatically exposes many new targets that you can leverage throughout you Run `make help` for a list of available targets. -**NOTE:** the `/` is interchangable with the `:` in target names +**NOTE:** the `/` is interchangable with the `:` in target names## Quick Start -## Makefile Targets +Here's how to get started... + +1. `git clone https://github.com/cloudposse/build-harness.git` to pull down the repository +2. `make init` to initialize the [`build-harness`](https://github.com/cloudposse/build-harness/) -```bash -$ make help - - Available targets: - -bash/lint Lint all bash scripts -docker/build Build docker image -docker/login Login into docker hub -docs/copyright-add Add copyright headers to source code -geodesic/deploy Run a Jenkins Job to Deploy $(APP) with $(CANONICAL_TAG) -git/aliases-update Update git aliases -git/export Export git vars -github/download-private-release Download release from github -github/download-public-release Download release from github -git/show Show vars -git/submodules-update Update submodules -go/build Build binary -go/build-all Build binary for all platforms -go/clean Clean compiled binary -go/clean-all Clean compiled binary and dependency -go/deps Install dependencies -go/deps-build Install dependencies for build -go/deps-dev Install development dependencies -go/fmt Format code according to Golang convention -go/install Install cli -go/lint Lint code -go/test Run tests -go/vet Vet code -helm/chart/build Build chart $CHART_NAME from $CHART_TPL -helm/chart/build-all Build chart $CHART_NAME from $CHART_TPL for all available $SEMVERSIONS -helm/chart/clean Clean chart packages -helm/chart/create Create chart $CHART from starter scaffold -helm/chart/publish Publish chart $CHART_NAME to $REPO_GATEWAY_ENDPOINT -helm/chart/starter/fetch Fetch starter -helm/chart/starter/remove Remove starter -helm/chart/starter/update Update starter -helm/install Install helm -helm/repo/add Add $REPO_NAME from $REPO_ENDPOINT -helm/repo/add-current Add helm remote dev repos -helm/repo/add-remote Add helm remote repos -helm/repo/build Build repo -helm/repo/clean Clean helm repo -helm/repo/fix-perms Fix repo filesystem permissions -helm/repo/info Show repo info -helm/repo/lint Lint charts -helm/repo/update Update repo info -helm/serve/index Build index for serve helm charts -help This help screen -jenkins/run-job-with-tag Run a Jenkins Job with $(TAG) -make/lint Lint all makefiles -readme Alias for readme/build -readme/build Create README.md by building it from .README.md file -readme/init Create basic minimalistic .README.md template file -readme/toc-update Update table of contents in README.md -semver/export Export semver vars -semver/show Show -stages/export Export stages vars -template/build Create $OUT file by building it from $IN template file -template/deps Install dependencies -terraform/get-modules Ensure all modules can be fetched -terraform/get-plugins Ensure all plugins can be fetched -terraform/install Install terraform -terraform/lint Lint check Terraform -terraform/validate Basic terraform sanity check -travis/docker-login Login into docker hub -travis/docker-tag-and-push Tag & Push according Travis environment variables -``` -## Real World Examples +## Examples +Here are some real world examples: - [`github-authorized-keys`](https://github.com/cloudposse/github-authorized-keys/) - A Golang project that leverages `docker/%`, `go/%`, `travis/%` targets - [`charts`](https://github.com/cloudposse/charts/) - A collection of Helm Charts that leverages `docker/%` and `helm/%` targets - [`bastion`](https://github.com/cloudposse/bastion/) - A docker image that leverages `docker/%` and `bash/lint` targets - [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label/) - A terraform module that leverages `terraform/%` targets + +## Makefile Targets +``` +Available targets: + + aws/install Install aws cli bundle + bash/lint Lint all bash scripts + chamber/install Install chamber + codefresh/trigger/webhook Trigger a CodeFresh WebHook + docker/build Build docker image + docker/login Login into docker hub + docs/copyright-add Add copyright headers to source code + geodesic/deploy Run a Jenkins Job to Deploy $(APP) with $(CANONICAL_TAG) + git/aliases-update Update git aliases + git/export Export git vars + git/show Show vars + git/submodules-update Update submodules + github/download-private-release Download release from github + github/download-public-release Download release from github + go/build Build binary + go/build-all Build binary for all platforms + go/clean Clean compiled binary + go/clean-all Clean compiled binary and dependency + go/deps Install dependencies + go/deps-build Install dependencies for build + go/deps-dev Install development dependencies + go/fmt Format code according to Golang convention + go/install Install cli + go/lint Lint code + go/test Run tests + go/vet Vet code + helm/chart/build Build chart $CHART_NAME from $CHART_TPL + helm/chart/build-all Build chart $CHART_NAME from $CHART_TPL for all available $SEMVERSIONS + helm/chart/clean Clean chart packages + helm/chart/create Create chart $CHART from starter scaffold + helm/chart/publish Publish chart $CHART_NAME to $REPO_GATEWAY_ENDPOINT + helm/chart/starter/fetch Fetch starter + helm/chart/starter/remove Remove starter + helm/chart/starter/update Update starter + helm/delete/namespace Delete all releases in a namespace as well as the namespace + helm/install Install helm + helm/repo/add Add $REPO_NAME from $REPO_ENDPOINT + helm/repo/add-current Add helm remote dev repos + helm/repo/add-remote Add helm remote repos + helm/repo/build Build repo + helm/repo/clean Clean helm repo + helm/repo/fix-perms Fix repo filesystem permissions + helm/repo/info Show repo info + helm/repo/lint Lint charts + helm/repo/update Update repo info + helm/serve/index Build index for serve helm charts + helm/toolbox/upsert Install or upgrade helm tiller + helmfile/install Install helmfile + help This help screen + jenkins/run-job-with-tag Run a Jenkins Job with $(TAG) + make/lint Lint all makefiles + packages/delete Delete packages + packages/install Install packages + packages/install/% Install package (e.g. helm, helmfile, kubectl) + packages/reinstall Reinstall packages + packages/uninstall/% Uninstall package (e.g. helm, helmfile, kubectl) + readme Alias for readme/build + readme/build Create README.md by building it from README.yaml + readme/init Create basic minimalistic .README.md template file + readme/lint Verify the `README.md` is up to date + semver/export Export semver vars + semver/show Show + stages/export Export stages vars + template/build Create $OUT file by building it from $IN template file + template/deps Install dependencies + terraform/get-modules Ensure all modules can be fetched + terraform/get-plugins Ensure all plugins can be fetched + terraform/install Install terraform + terraform/lint Lint check Terraform + terraform/validate Basic terraform sanity check + travis/docker-login Login into docker hub + travis/docker-tag-and-push Tag & Push according Travis environment variables + +``` + + + +## Related Projects + +Check out these related projects. + +- [Packages](https://github.com/cloudposse/packages) - Cloud Posse installer and distribution of native apps +- [Dev Harness](https://github.com/cloudposse/dev) - Cloud Posse Local Development Harness + + ## Help **Got a question?** -File a GitHub [issue](https://github.com/cloudposse/build-harness/issues), send us an [email](mailto:hello@cloudposse.com) or reach out to us on [Gitter](https://gitter.im/cloudposse/). +File a GitHub [issue](https://github.com/cloudposse/build-harness/issues), send us an [email][email] or join our [Slack Community][slack]. + +## Commerical Support + +Work directly with our team of DevOps experts via email, slack, and video conferencing. + +We provide *commercial support* for all of our [Open Source][github] projects. As a *Dedicated Support* customer, you have access to our team of subject matter experts at a fraction of the cost of a fulltime engineer. + +- **Questions.** We'll use a Shared Slack channel between your team and ours. +- **Troubleshooting.** We'll help you triage why things aren't working. +- **Code Reviews.** We'll review your Pull Requests and provide constructive feedback. +- **Bug Fixes.** We'll rapidly work to fix any bugs in our projects. +- **Build New Terraform Modules.** We'll develop original modules to provision infrastructure. +- **Cloud Architecture.** We'll assist with your cloud strategy and design. +- **Implementation.** We'll provide hands on support to implement our reference architectures. + +## Community Forum + +Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build *sweet* infrastructure. + ## Contributing ### Bug Reports & Feature Requests @@ -118,7 +166,7 @@ Please use the [issue tracker](https://github.com/cloudposse/build-harness/issue ### Developing -If you are interested in being a contributor and want to get involved in developing `build-harness`, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com). +If you are interested in being a contributor and want to get involved in developing this project or [help out](https://github.com/orgs/cloudposse/projects/3) with our other projects, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com). In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. @@ -126,20 +174,16 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. 2. **Clone** the project to your own machine 3. **Commit** changes to your own branch 4. **Push** your work back up to your fork - 5. Submit a **Pull request** so that we can review your changes + 5. Submit a **Pull Request** so that we can review your changes -**NOTE:** Be sure to merge the latest from "upstream" before making a pull request! +**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request! -Here's how to get started... - -1. `git clone https://github.com/cloudposse/build-harness.git` to pull down the repository -2. `make init` to initialize the [`build-harness`](https://github.com/cloudposse/build-harness/) -3. Review the [documentation](docs/) on compiling +## License -## License +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -[APACHE 2.0](LICENSE) © 2017 [Cloud Posse, LLC](https://cloudposse.com) +Copyright © 2017-2018 [Cloud Posse, LLC](https://cloudposse.com) See [LICENSE](LICENSE) for full details. @@ -151,7 +195,7 @@ See [LICENSE](LICENSE) for full details. "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an @@ -159,41 +203,49 @@ See [LICENSE](LICENSE) for full details. KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -## About -This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at -We love [Open Source Software](https://github.com/cloudposse/)! +## About -See [our other projects][community] -or [hire us][hire] to help build your next cloud-platform. +This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at - [website]: http://cloudposse.com/ - [community]: https://github.com/cloudposse/ - [hire]: http://cloudposse.com/contact/ +[![Cloud Posse](https://cloudposse.com/logo-300x69.png)](https://cloudposse.com) -### Contributors +We're a [DevOps Professional Services][hire] company based in Los Angeles, CA. We love [Open Source Software](https://github.com/cloudposse/)! -|[![Erik Osterman][erik_img]][erik_web]
[Erik Osterman][erik_web] |[![Igor Rodionov][igor_img]][igor_web]
[Igor Rodionov][igor_img] |[![Andriy Knysh][andriy_img]][andriy_web]
[Andriy Knysh][andriy_web] | -|---|---|---| +We offer paid support on all of our projects. -[andriy_img]: https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[andriy_web]: https://github.com/aknysh/ +Check out [our other projects][github], [apply for a job][jobs], or [hire us][hire] to help with your cloud strategy and implementation. -[erik_img]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144 -[erik_web]: https://github.com/osterman/ + [docs]: https://docs.cloudposse.com/ + [website]: https://cloudposse.com/ + [github]: https://github.com/cloudposse/ + [jobs]: https://cloudposse.com/jobs/ + [hire]: https://cloudposse.com/contact/ + [slack]: https://slack.cloudposse.com/ + [linkedin]: https://www.linkedin.com/company/cloudposse + [twitter]: https://twitter.com/cloudposse/ + [email]: mailto:hello@cloudposse.com -[igor_img]: http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144 -[igor_web]: https://github.com/goruha/ -[konstantin_img]: https://avatars1.githubusercontent.com/u/11299538?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[konstantin_web]: https://github.com/comeanother/ +### Contributors -[sergey_img]: https://avatars1.githubusercontent.com/u/1134449?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[sergey_web]: https://github.com/s2504s/ +| [![Erik Osterman][osterman_avatar]](osterman_homepage)
[Erik Osterman][osterman_homepage] | [![Igor Rodionov][goruha_avatar]](goruha_homepage)
[Igor Rodionov][goruha_homepage] | [![Andriy Knysh][aknysh_avatar]](aknysh_homepage)
[Andriy Knysh][aknysh_homepage] | [![Konstantin][comeanother_avatar]](comeanother_homepage)
[Konstantin][comeanother_homepage] | [![Sergey][s2504s_avatar]](s2504s_homepage)
[Sergey][s2504s_homepage] | [![Valeriy][drama17_avatar]](drama17_homepage)
[Valeriy][drama17_homepage] | [![Vladimir][SweetOps_avatar]](SweetOps_homepage)
[Vladimir][SweetOps_homepage] | +|---|---|---|---|---|---|---| + + [osterman_homepage]: https://github.com/osterman + [osterman_avatar]: http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144 + [goruha_homepage]: https://github.com/goruha/ + [goruha_avatar]: http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144 + [aknysh_homepage]: https://github.com/aknysh/ + [aknysh_avatar]: https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 + [comeanother_homepage]: https://github.com/comeanother/ + [comeanother_avatar]: https://avatars1.githubusercontent.com/u/11299538?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 + [s2504s_homepage]: https://github.com/s2504s/ + [s2504s_avatar]: https://avatars1.githubusercontent.com/u/1134449?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 + [drama17_homepage]: https://github.com/drama17/ + [drama17_avatar]: https://avatars1.githubusercontent.com/u/10601658?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 + [SweetOps_homepage]: https://github.com/SweetOps/ + [SweetOps_avatar]: https://avatars1.githubusercontent.com/u/26582191?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[valeriy_img]: https://avatars1.githubusercontent.com/u/10601658?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[valeriy_web]: https://github.com/drama17/ -[vladimir_img]: https://avatars1.githubusercontent.com/u/26582191?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144 -[vladimir_web]: https://github.com/SweetOps/ diff --git a/README.yaml b/README.yaml new file mode 100644 index 00000000..ebd8acd0 --- /dev/null +++ b/README.yaml @@ -0,0 +1,108 @@ +--- +# +# This is the canonical configuration for the `README.md` +# Run `make readme` to rebuild the `README.md` +# + +# Name of this project +name: Build Harness + +# Logo for this project +#logo: docs/logo.png + +# License of this project +license: "APACHE2" + +# Canonical GitHub repo +github_repo: cloudposse/build-harness + +# Badges to display +badges: + - name: "Build Status" + image: "https://travis-ci.org/cloudposse/build-harness.svg?branch=master" + url: "https://travis-ci.org/cloudposse/build-harness" + - name: "Latest Release" + image: "https://img.shields.io/github/release/cloudposse/build-harness.svg" + url: "https://github.com/cloudposse/build-harness/releases" + - name: "Slack Community" + image: "https://slack.cloudposse.com/badge.svg" + url: "https://slack.cloudposse.com" + +related: + - name: "Packages" + description: "Cloud Posse installer and distribution of native apps" + url: "https://github.com/cloudposse/packages" + - name: "Dev Harness" + description: "Cloud Posse Local Development Harness" + url: "https://github.com/cloudposse/dev" + +# Short description of this project +description: |- + This `build-harness` is a collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more. + It's designed to work with CI/CD systems such as Travis CI, CircleCI and Jenkins. + +# How to use this project +usage: |- + At the top of your `Makefile` add, the following... + + ```make + -include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness) + ``` + + This will download a `Makefile` called `.build-harness` and include it at run-time. We recommend adding the `.build-harness` file to your `.gitignore`. + + This automatically exposes many new targets that you can leverage throughout your build & CI/CD process. + + Run `make help` for a list of available targets. + + **NOTE:** the `/` is interchangable with the `:` in target names + +# Example usage +examples: |- + Here are some real world examples: + - [`github-authorized-keys`](https://github.com/cloudposse/github-authorized-keys/) - A Golang project that leverages `docker/%`, `go/%`, `travis/%` targets + - [`charts`](https://github.com/cloudposse/charts/) - A collection of Helm Charts that leverages `docker/%` and `helm/%` targets + - [`bastion`](https://github.com/cloudposse/bastion/) - A docker image that leverages `docker/%` and `bash/lint` targets + - [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label/) - A terraform module that leverages `terraform/%` targets + +# How to get started quickly +quickstart: |- + Here's how to get started... + + 1. `git clone https://github.com/cloudposse/build-harness.git` to pull down the repository + 2. `make init` to initialize the [`build-harness`](https://github.com/cloudposse/build-harness/) + +# Other files to include in this README from the project folder +include: + - "docs/targets.md" + +# Contributors to this project +contributors: + - name: "Erik Osterman" + homepage: "https://github.com/osterman" + avatar: "http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144" + github: "osterman" + - name: "Igor Rodionov" + homepage: "https://github.com/goruha/" + avatar: "http://s.gravatar.com/avatar/bc70834d32ed4517568a1feb0b9be7e2?s=144" + github: "goruha" + - name: "Andriy Knysh" + homepage: "https://github.com/aknysh/" + avatar: "https://avatars0.githubusercontent.com/u/7356997?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144" + github: "aknysh" + - name: "Konstantin" + homepage: "https://github.com/comeanother/" + avatar: "https://avatars1.githubusercontent.com/u/11299538?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144" + github: "comeanother" + - name: "Sergey" + homepage: "https://github.com/s2504s/" + avatar: "https://avatars1.githubusercontent.com/u/1134449?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144" + github: "s2504s" + - name: "Valeriy" + homepage: "https://github.com/drama17/" + avatar: "https://avatars1.githubusercontent.com/u/10601658?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144" + github: "drama17" + - name: "Vladimir" + homepage: "https://github.com/SweetOps/" + avatar: "https://avatars1.githubusercontent.com/u/26582191?v=4&u=ed9ce1c9151d552d985bdf5546772e14ef7ab617&s=144" + github: "SweetOps" diff --git a/docs/targets.md b/docs/targets.md new file mode 100644 index 00000000..f27a60f9 --- /dev/null +++ b/docs/targets.md @@ -0,0 +1,78 @@ +## Makefile Targets +``` +Available targets: + + aws/install Install aws cli bundle + bash/lint Lint all bash scripts + chamber/install Install chamber + codefresh/trigger/webhook Trigger a CodeFresh WebHook + docker/build Build docker image + docker/login Login into docker hub + docs/copyright-add Add copyright headers to source code + geodesic/deploy Run a Jenkins Job to Deploy $(APP) with $(CANONICAL_TAG) + git/aliases-update Update git aliases + git/export Export git vars + git/show Show vars + git/submodules-update Update submodules + github/download-private-release Download release from github + github/download-public-release Download release from github + go/build Build binary + go/build-all Build binary for all platforms + go/clean Clean compiled binary + go/clean-all Clean compiled binary and dependency + go/deps Install dependencies + go/deps-build Install dependencies for build + go/deps-dev Install development dependencies + go/fmt Format code according to Golang convention + go/install Install cli + go/lint Lint code + go/test Run tests + go/vet Vet code + helm/chart/build Build chart $CHART_NAME from $CHART_TPL + helm/chart/build-all Build chart $CHART_NAME from $CHART_TPL for all available $SEMVERSIONS + helm/chart/clean Clean chart packages + helm/chart/create Create chart $CHART from starter scaffold + helm/chart/publish Publish chart $CHART_NAME to $REPO_GATEWAY_ENDPOINT + helm/chart/starter/fetch Fetch starter + helm/chart/starter/remove Remove starter + helm/chart/starter/update Update starter + helm/delete/namespace Delete all releases in a namespace as well as the namespace + helm/install Install helm + helm/repo/add Add $REPO_NAME from $REPO_ENDPOINT + helm/repo/add-current Add helm remote dev repos + helm/repo/add-remote Add helm remote repos + helm/repo/build Build repo + helm/repo/clean Clean helm repo + helm/repo/fix-perms Fix repo filesystem permissions + helm/repo/info Show repo info + helm/repo/lint Lint charts + helm/repo/update Update repo info + helm/serve/index Build index for serve helm charts + helm/toolbox/upsert Install or upgrade helm tiller + helmfile/install Install helmfile + help This help screen + jenkins/run-job-with-tag Run a Jenkins Job with $(TAG) + make/lint Lint all makefiles + packages/delete Delete packages + packages/install Install packages + packages/install/% Install package (e.g. helm, helmfile, kubectl) + packages/reinstall Reinstall packages + packages/uninstall/% Uninstall package (e.g. helm, helmfile, kubectl) + readme Alias for readme/build + readme/build Create README.md by building it from README.yaml + readme/init Create basic minimalistic .README.md template file + readme/lint Verify the `README.md` is up to date + semver/export Export semver vars + semver/show Show + stages/export Export stages vars + template/build Create $OUT file by building it from $IN template file + template/deps Install dependencies + terraform/get-modules Ensure all modules can be fetched + terraform/get-plugins Ensure all plugins can be fetched + terraform/install Install terraform + terraform/lint Lint check Terraform + terraform/validate Basic terraform sanity check + travis/docker-login Login into docker hub + travis/docker-tag-and-push Tag & Push according Travis environment variables + +``` diff --git a/modules/docs/Makefile b/modules/docs/Makefile new file mode 100644 index 00000000..ac8cd972 --- /dev/null +++ b/modules/docs/Makefile @@ -0,0 +1,14 @@ +.PHONY : docs/targets.md +## Update `docs/targets.md` from `make help` +docs/targets.md: + @( \ + echo "## Makefile Targets"; \ + echo '```'; \ + $(SELF) --no-print-directory --quiet --silent help | sed $$'s,\x1b\\[[0-9;]*[a-zA-Z],,g'; \ + echo '```'; \ + ) > $@ + +.PHONY : docs/terraform.md +## Update `docs/terraform.md` from `terraform-docs` +docs/terraform.md: packages/install/terraform-docs + @terraform-docs md . > $@ diff --git a/modules/packages/Makefile b/modules/packages/Makefile index 4adc6a5b..857c510e 100644 --- a/modules/packages/Makefile +++ b/modules/packages/Makefile @@ -1,7 +1,15 @@ export INSTALL_PATH ?= $(BUILD_HARNESS_PATH)/vendor -export PACKAGES_VERSION ?= 0.1.7 +export PACKAGES_VERSION ?= 0.2.1 export PACKAGES_PATH ?= $(BUILD_HARNESS_PATH)/vendor/packages +## Delete packages +packages/delete: + rm -rf $(PACKAGES_PATH) + +## Reinstall packages +packages/reinstall: packages/delete packages/install + @exit 0 + ## Install packages packages/install: @if [ ! -d $(PACKAGES_PATH) ]; then \ diff --git a/modules/readme/Makefile b/modules/readme/Makefile index 60600c08..adc84c32 100644 --- a/modules/readme/Makefile +++ b/modules/readme/Makefile @@ -1,23 +1,36 @@ +export README_LINT ?= $(TMP)/README.md export README_FILE ?= README.md -export README_TEMPLATE_FILE ?= .$(README_FILE) +export README_YAML ?= README.yaml +export README_TEMPLATE_FILE ?= $(BUILD_HARNESS_PATH)/templates/README.md +export README_TEMPLATE_YAML ?= $(BUILD_HARNESS_PATH)/templates/README.yaml ## Alias for readme/build readme: readme/build @exit 0 -## Update table of contents in README.md -readme/toc-update: - @doctoc --notitle --github $(README_FILE) +readme/deps: packages/install/gomplate + @exit 0 ## Create basic minimalistic .README.md template file readme/init: - @if [ -s ./$(README_TEMPLATE_FILE) ]; then \ - echo "$(README_TEMPLATE_FILE) already exists!"; \ + @if [ -f $(README_YAML) ]; then \ + echo "$(README_YAML) already exists!"; \ else \ - cp $(BUILD_HARNESS_PATH)/templates/$(README_TEMPLATE_FILE) ./$(README_TEMPLATE_FILE) ; \ - echo "$(README_TEMPLATE_FILE) created!"; \ + cp $(README_TEMPLATE_YAML) $(README_YAML) ; \ + echo "$(README_YAML) created!"; \ fi; -## Create README.md by building it from .README.md file -readme/build: - @$(SELF) -s template/build IN=$(README_TEMPLATE_FILE) OUT=$(README_FILE) +## Verify the `README.md` is up to date +readme/lint: + @$(SELF) readme/build README_FILE=$(README_LINT) >/dev/null + @diff -ruN $(README_LINT) $(README_FILE) + @rm -f $(README_LINT) + +## Create README.md by building it from README.yaml +readme/build: $(README_DEPS) + @mkdir -p docs + @gomplate --file $(README_TEMPLATE_FILE) \ + --out $(README_FILE) \ + --datasource config=$(README_YAML) \ + --datasource includes='file://$(shell pwd)/?type=text/plain' + @echo "Generated $(README_FILE) from $(README_TEMPLATE_FILE) using data from $(README_TEMPLATE_YAML)" diff --git a/modules/template/Makefile b/modules/template/Makefile index b4cc2a66..6636add4 100644 --- a/modules/template/Makefile +++ b/modules/template/Makefile @@ -1,5 +1,5 @@ export GOMPLATE ?= $(BUILD_HARNESS_PATH)/vendor/gomplate -GOMPLATE_VERSION ?= v2.2.0 +GOMPLATE_VERSION ?= v2.6.0 GOMPLATE_REPO ?= hairyhenderson/gomplate ## Install dependencies diff --git a/templates/README.md b/templates/README.md index 45822aec..478d4ecf 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,16 +1,156 @@ -## {{ .Env.NAME }} -{{ (datasource "section").warning }} -{{ .Env.DESCRIPTION }} + -{{ (datasource "section").help }} -{{ (datasource "section").contributing }} -{{ (datasource "license").apache2 }} -{{ (datasource "section").about }} +[![Cloud Posse](https://cloudposse.com/logo-300x69.png)](https://cloudposse.com) +# {{(ds "config").name}} {{ if has (ds "config") "badges" }}{{- range $badge := (ds "config").badges -}}{{ printf " [![%s](%s)](%s)" $badge.name $badge.image $badge.url }}{{ end }}{{ end }} + +{{ if has (ds "config") "logo" }} +![{{(ds "config").name}}]({{ (ds "config").logo }}) +{{- end -}} + +{{ if has (ds "config") "description" }} +{{(ds "config").description }} +{{- end -}} + +This project is part of our comprehensive ["SweetOps"](https://docs.cloudposse.com) approach towards DevOps. + +{{ if eq (ds "config").license "APACHE2" }} +It's 100% Open Source and licensed under [APACHE2](LICENSE). +{{ end }} + +{{ if has (ds "config") "usage" }} +## Usage + +{{ (ds "config").usage -}} +{{ end }} + +{{- if has (ds "config") "quickstart" -}} +## Quick Start + +{{ (ds "config").quickstart -}} +{{ end }} + +{{ if has (ds "config") "examples" }} +## Examples + +{{(ds "config").examples }} +{{ end }} + +{{ if has (ds "config") "include" }} +{{ range $file := (datasource "config").include -}} +{{ (include "includes" $file) }} +{{- end }} +{{- end }} +{{ if has (ds "config") "related" }} + +## Related Projects + +Check out these related projects. +{{ range $related := (ds "config").related }} +{{ printf "- [%s](%s) - %s" $related.name $related.url $related.description }}{{ end }} + +{{ end}} +## Help + +**Got a question?** + +File a GitHub [issue]({{ printf "https://github.com/%s/issues" (ds "config").github_repo}}), send us an [email][email] or join our [Slack Community][slack]. + +## Commerical Support + +Work directly with our team of DevOps experts via email, slack, and video conferencing. + +We provide *commercial support* for all of our [Open Source][github] projects. As a *Dedicated Support* customer, you have access to our team of subject matter experts at a fraction of the cost of a fulltime engineer. + +- **Questions.** We'll use a Shared Slack channel between your team and ours. +- **Troubleshooting.** We'll help you triage why things aren't working. +- **Code Reviews.** We'll review your Pull Requests and provide constructive feedback. +- **Bug Fixes.** We'll rapidly work to fix any bugs in our projects. +- **Build New Terraform Modules.** We'll develop original modules to provision infrastructure. +- **Cloud Architecture.** We'll assist with your cloud strategy and design. +- **Implementation.** We'll provide hands on support to implement our reference architectures. + +## Community Forum + +Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build *sweet* infrastructure. + +## Contributing + +### Bug Reports & Feature Requests + +Please use the [issue tracker]({{ printf "https://github.com/%s/issues" (ds "config").github_repo}}) to report any bugs or file feature requests. + +### Developing + +If you are interested in being a contributor and want to get involved in developing this project or [help out](https://github.com/orgs/cloudposse/projects/3) with our other projects, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com). + +In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. + + 1. **Fork** the repo on GitHub + 2. **Clone** the project to your own machine + 3. **Commit** changes to your own branch + 4. **Push** your work back up to your fork + 5. Submit a **Pull Request** so that we can review your changes + +**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request! + +{{ if eq (ds "config").license "APACHE2" }} +## License + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) + +Copyright © 2017-{{ time.Now.Year }} [Cloud Posse, LLC](https://cloudposse.com) + +See [LICENSE](LICENSE) for full details. + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +{{ end }} + +## About + +This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at + +[![Cloud Posse](https://cloudposse.com/logo-300x69.png)](https://cloudposse.com) + +We're a [DevOps Professional Services][hire] company based in Los Angeles, CA. We love [Open Source Software](https://github.com/cloudposse/)! + +We offer paid support on all of our projects. + +Check out [our other projects][github], [apply for a job][jobs], or [hire us][hire] to help with your cloud strategy and implementation. + + [docs]: https://docs.cloudposse.com/ + [website]: https://cloudposse.com/ + [github]: https://github.com/cloudposse/ + [jobs]: https://cloudposse.com/jobs/ + [hire]: https://cloudposse.com/contact/ + [slack]: https://slack.cloudposse.com/ + [linkedin]: https://www.linkedin.com/company/cloudposse + [twitter]: https://twitter.com/cloudposse/ + [email]: mailto:hello@cloudposse.com + +{{ if has (datasource "config") "contributors" }} ### Contributors -| -{{- (datasource "contributor").erik }} | -|---| +| {{ range $contributor := (ds "config").contributors }}{{ printf " [![%s][%s_avatar]](%s_homepage)
[%s][%s_homepage] |" $contributor.name $contributor.github $contributor.github $contributor.name $contributor.github}}{{ end }} +|{{- range $contributor := (ds "config").contributors -}}---|{{ end }} -{{ (datasource "contributor")._links }} +{{ range $contributor := (ds "config").contributors -}} +{{ printf " [%s_homepage]: %s" $contributor.github $contributor.homepage }} +{{ printf " [%s_avatar]: %s" $contributor.github $contributor.avatar }} +{{ end }} +{{ end }}