From c71c70a73e1c50a28ed7e9fb992bb3ecdf99ed4f Mon Sep 17 00:00:00 2001 From: Bill Monkman Date: Fri, 15 May 2020 16:34:58 -0700 Subject: [PATCH] Copy some of the readme from the old zero project --- OLD-README.md | 278 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 283 +++----------------------------------------------- 2 files changed, 294 insertions(+), 267 deletions(-) create mode 100644 OLD-README.md diff --git a/OLD-README.md b/OLD-README.md new file mode 100644 index 000000000..a3831b672 --- /dev/null +++ b/OLD-README.md @@ -0,0 +1,278 @@ +# Commit0 [POC] + +**NOTE** 🛑 This is a proof of concept application. Before you start using this +tool please talk to the team in the `#product-commit0` slack channel so we can +give you better instructions on how to get started. + +[![Build Status](https://travis-ci.org/commitdev/commit0.svg)](https://travis-ci.org/commitdev/commit0) +[![Go Report Card](https://goreportcard.com/badge/github.com/commitdev/commit0?style=flat-square)](https://goreportcard.com/report/github.com/commitdev/commit0) +[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/commitdev/commit0) + +Status: Proof of Concept + +## About Commit0 +Commit0 is a project skaffolding framework and ecosystem created to: + +1. Maximize knowledge sharing across an organization +2. Easily maintain a state of the art and easily reusable implementations of production grade solutions to recurring problems +3. Re-create the seamless deployment experience offered by PaaS solutions but with a fully open source stack that follows industry best practices + +With Commit0: +- Easily deploy and integrate various boilerplate solutions +- Instantly integrate commonly used open source microservices for authentication, user management, file encryption, image resizing etc. +- Get a simple Push-To-Deploy workflow that you are accustomed to with popular PaaS solutions [TODO] +- There's no vendor lock-in. It's all implemented with open source tools and deployed to your own cloud provider. + +## Commit0 Generator CLI +Commit0 CLI is an opinionated, yet fully modular code generation tool with declarative syntax that allows developers to easily integrate user prompts and interactions. + +Problems we encountered: +- It was tedious to create reusable templates and hard to maintain +- Lack of standardization and integration interface between the templates +- Difficult to integrate individually templated codebases + +How we aim to address those issues: +- Make templating behaviour simple and declarative +- Clear strategy and guideline around what are clear and reusable templates +- Standardize how templated code should get dependent parameters and start up + +This is inspired by: +- [Yeoman Generator](https://github.com/yeoman/generator) +- [JHipster](https://github.com/jhipster/generator-jhipster) +- [Boilr](https://github.com/tmrts/boilr) + + +## Installation + +As there some dependencies it will be easier to use this tool within the provided image, clone the repo and then run `make build-docker-local`. +The best way then to use this is to add an alias, then you can use the CLI as if it was installed as usual on your machine: +`alias commit0='docker run -it -v "$(pwd):/project" -v "${HOME}/.aws:/root/.aws" commit0:v0'` + +# Usage + +1) To create a project run `commit0 create [PROJECT_NAME]` +2) It will prompt you to select a cloud provider and an account profile to use +3) A folder `PROJECT_NAME` will be created. You can `cd [PROJECT_NAME]` and configure the example `commit0.yml` that's generated +4) Run `commit0 generate -c ` to generate all the all the project repos +5) You can go to each project repo and follow the project readme to start the service +6) `commit0 ui` launches the locally hosted web UI (Static SPA) and the API server + + +## Configuring Commit0 + +This is a guide on how to configure your project manually with a single file `commit0.yml`. Simply write this file to the root of your project directory and run the commit0 CLI tool against it to generate your project files. + +* [commit0.yml](#commit0-yaml) + * [name*](#name) + * [context](#context) + * [modules*](#modules) + * [source*](#module-source) + * [params*](#module-params) + * [output](#module-output) + * [overwrite](#module-overwrite) +* [commit0.module.yml](#commit0-module-yaml) + * [name*](#module-name) + * [description](#module-description) + * [prompts](#module-prompts) + * [field*](#prompt-field) + * [label](#prompt-label) + * [options](#prompt-options) + * [template](#template) + * [extension](#template-extension) + * [delimiters](#template-delimiters) + * [output](#template-output) + +## Commit0.yaml +Your project config file. It describes the project +Example: +``` +name: newProject +context: + cognitoPoolID: xxx +modules: + - source: "github.com/commitdev/commit0-aws-eks-stack" + output: "infrastructure" + - source: "github.com/zthomas/react-mui-kit" + output: "web-app" +``` + +## Name +Name of your project. This will be used to name the github repos as well as in other parts of the generated code. + +[]() | | +--- | --- +Required | True +Type | String + +## Context +A key value map of global context parameters to use in the templates. + +[]() | | +--- | --- +Required | False +Type | Map[String] + +## Modules +List of modules template modules to import + +[]() | | +--- | --- +Required | True +Type | Map[Module] + +## Source +We are using go-getter to parse the sources, we you can use any URL or file formats that [go-getter](https://github.com/hashicorp/go-getter#url-format) supports. + +[]() | | +--- | --- +Required | True +Type | String + +## Params +Module parameters to use during templating + +[]() | | +--- | --- +Required | True +Type | String + +## Output +Template output directory that the current module should write to. + +[]() | | +--- | --- +Required | False +Type | String + +## Overwrite +Whether to overwrite existing files when generating files from templates + +[]() | | +--- | --- +Required | False +Type | Boolean +Default | False + + +## Commit0.module.yaml +The module config file. You can configure how the templating engine should process the files in the current repository. +Example: +``` +name: react-mui-kit +template: + extension: '.tmplt' + delimiters: + - '<%' + - '%>' + output: web-app +``` + +## Name +Name of your module. This will be used as the default module directory as well as a display name in the prompts. + +[]() | | +--- | --- +Required | True +Type | String + +## Description +Short description of the module + +[]() | | +--- | --- +Required | False +Type | String + +## template +Template configurations +[]() | | +--- | --- +Required | False +Type | Map + +## Extension +File extension to signify that a file is a template. If this is defined, non-template files will not be parsed and will be copied over directly. The default value is `.tmplt` + +[]() | | +--- | --- +Required | False +Type | Map + +## Delimiters +An pair of delimiters that the template engine should use. The default values are: `{{`, `}}` + +[]() | | +--- | --- +Required | False +Type | Map[String] + +## Output +The default template output directory that you want the template engine to write to. This will be overwritten by the + +[]() | | +--- | --- +Required | False +Type | String + +## Prompts +User prompts to generate to collect additional module specific params +[]() | | +--- | --- +Required | False +Type | Map + +## Field +The name of the field that the param should be written to + +[]() | | +--- | --- +Required | True +Type | String + +## Label +The message that will be presented to the user + +[]() | | +--- | --- +Required | False +Type | String + +## Options +A list of options to select from. If not given, then it will be rendered as a text input prompt. + +[]() | | +--- | --- +Required | False +Type | Map[String] + +# Development +We are looking for contributors! + +Building from the source +``` +make install-go +``` +Compile a new `commit0` binary in the working directory +``` +make build +``` + +Now you can either add your project directory to your path or just execute it directly +``` +mkdir tmp +cd tmp +../commit0 create test-app +cd test-app +../../commit0 generate -c commit0.yml +``` + +To run a single test for development +``` +go test -run TestGenerateModules "github.com/commitdev/commit0/internal/generate" -v +``` + +### Building locally +As there are some dependencies it will be easier to use this tool within the provided image, clone the repo and then run `make build-docker-local`. + +The best way then to use this is to add an alias, then you can use the CLI as if it was installed as usual on your machine: +`alias commit0='docker run -it -v "$(pwd):/project" commit0:v0'` diff --git a/README.md b/README.md index a3831b672..c95023b3d 100644 --- a/README.md +++ b/README.md @@ -1,278 +1,27 @@ -# Commit0 [POC] +![zero](https://github.com/commitdev/zero/blob/master/docs/img/logo-small.png?raw=true) -**NOTE** 🛑 This is a proof of concept application. Before you start using this -tool please talk to the team in the `#product-commit0` slack channel so we can -give you better instructions on how to get started. +This is a WIP version of our tool Zero which aims to make it quick and easy for developers to bootstrap a new environment and get to writing code. -[![Build Status](https://travis-ci.org/commitdev/commit0.svg)](https://travis-ci.org/commitdev/commit0) -[![Go Report Card](https://goreportcard.com/badge/github.com/commitdev/commit0?style=flat-square)](https://goreportcard.com/report/github.com/commitdev/commit0) -[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/commitdev/commit0) +For the older, simple tool that just rendered templates, see [commitdev/zero-old][old] +## Getting Started -Status: Proof of Concept +TBD -## About Commit0 -Commit0 is a project skaffolding framework and ecosystem created to: +#### Building this tool -1. Maximize knowledge sharing across an organization -2. Easily maintain a state of the art and easily reusable implementations of production grade solutions to recurring problems -3. Re-create the seamless deployment experience offered by PaaS solutions but with a fully open source stack that follows industry best practices - -With Commit0: -- Easily deploy and integrate various boilerplate solutions -- Instantly integrate commonly used open source microservices for authentication, user management, file encryption, image resizing etc. -- Get a simple Push-To-Deploy workflow that you are accustomed to with popular PaaS solutions [TODO] -- There's no vendor lock-in. It's all implemented with open source tools and deployed to your own cloud provider. - -## Commit0 Generator CLI -Commit0 CLI is an opinionated, yet fully modular code generation tool with declarative syntax that allows developers to easily integrate user prompts and interactions. - -Problems we encountered: -- It was tedious to create reusable templates and hard to maintain -- Lack of standardization and integration interface between the templates -- Difficult to integrate individually templated codebases - -How we aim to address those issues: -- Make templating behaviour simple and declarative -- Clear strategy and guideline around what are clear and reusable templates -- Standardize how templated code should get dependent parameters and start up - -This is inspired by: -- [Yeoman Generator](https://github.com/yeoman/generator) -- [JHipster](https://github.com/jhipster/generator-jhipster) -- [Boilr](https://github.com/tmrts/boilr) - - -## Installation - -As there some dependencies it will be easier to use this tool within the provided image, clone the repo and then run `make build-docker-local`. -The best way then to use this is to add an alias, then you can use the CLI as if it was installed as usual on your machine: -`alias commit0='docker run -it -v "$(pwd):/project" -v "${HOME}/.aws:/root/.aws" commit0:v0'` - -# Usage - -1) To create a project run `commit0 create [PROJECT_NAME]` -2) It will prompt you to select a cloud provider and an account profile to use -3) A folder `PROJECT_NAME` will be created. You can `cd [PROJECT_NAME]` and configure the example `commit0.yml` that's generated -4) Run `commit0 generate -c ` to generate all the all the project repos -5) You can go to each project repo and follow the project readme to start the service -6) `commit0 ui` launches the locally hosted web UI (Static SPA) and the API server - - -## Configuring Commit0 - -This is a guide on how to configure your project manually with a single file `commit0.yml`. Simply write this file to the root of your project directory and run the commit0 CLI tool against it to generate your project files. - -* [commit0.yml](#commit0-yaml) - * [name*](#name) - * [context](#context) - * [modules*](#modules) - * [source*](#module-source) - * [params*](#module-params) - * [output](#module-output) - * [overwrite](#module-overwrite) -* [commit0.module.yml](#commit0-module-yaml) - * [name*](#module-name) - * [description](#module-description) - * [prompts](#module-prompts) - * [field*](#prompt-field) - * [label](#prompt-label) - * [options](#prompt-options) - * [template](#template) - * [extension](#template-extension) - * [delimiters](#template-delimiters) - * [output](#template-output) - -## Commit0.yaml -Your project config file. It describes the project -Example: +```shell +$ git clone git@github.com:commitdev/zero.git +$ cd zero && make ``` -name: newProject -context: - cognitoPoolID: xxx -modules: - - source: "github.com/commitdev/commit0-aws-eks-stack" - output: "infrastructure" - - source: "github.com/zthomas/react-mui-kit" - output: "web-app" -``` -## Name -Name of your project. This will be used to name the github repos as well as in other parts of the generated code. +## Planning and Process -[]() | | ---- | --- -Required | True -Type | String - -## Context -A key value map of global context parameters to use in the templates. - -[]() | | ---- | --- -Required | False -Type | Map[String] - -## Modules -List of modules template modules to import - -[]() | | ---- | --- -Required | True -Type | Map[Module] - -## Source -We are using go-getter to parse the sources, we you can use any URL or file formats that [go-getter](https://github.com/hashicorp/go-getter#url-format) supports. - -[]() | | ---- | --- -Required | True -Type | String - -## Params -Module parameters to use during templating - -[]() | | ---- | --- -Required | True -Type | String - -## Output -Template output directory that the current module should write to. - -[]() | | ---- | --- -Required | False -Type | String - -## Overwrite -Whether to overwrite existing files when generating files from templates - -[]() | | ---- | --- -Required | False -Type | Boolean -Default | False - - -## Commit0.module.yaml -The module config file. You can configure how the templating engine should process the files in the current repository. -Example: -``` -name: react-mui-kit -template: - extension: '.tmplt' - delimiters: - - '<%' - - '%>' - output: web-app -``` +Documents should all be stored in the [Commit Zero Google Drive][drive] -## Name -Name of your module. This will be used as the default module directory as well as a display name in the prompts. - -[]() | | ---- | --- -Required | True -Type | String - -## Description -Short description of the module - -[]() | | ---- | --- -Required | False -Type | String - -## template -Template configurations -[]() | | ---- | --- -Required | False -Type | Map - -## Extension -File extension to signify that a file is a template. If this is defined, non-template files will not be parsed and will be copied over directly. The default value is `.tmplt` - -[]() | | ---- | --- -Required | False -Type | Map - -## Delimiters -An pair of delimiters that the template engine should use. The default values are: `{{`, `}}` - -[]() | | ---- | --- -Required | False -Type | Map[String] - -## Output -The default template output directory that you want the template engine to write to. This will be overwritten by the - -[]() | | ---- | --- -Required | False -Type | String - -## Prompts -User prompts to generate to collect additional module specific params -[]() | | ---- | --- -Required | False -Type | Map - -## Field -The name of the field that the param should be written to - -[]() | | ---- | --- -Required | True -Type | String - -## Label -The message that will be presented to the user - -[]() | | ---- | --- -Required | False -Type | String - -## Options -A list of options to select from. If not given, then it will be rendered as a text input prompt. - -[]() | | ---- | --- -Required | False -Type | Map[String] - -# Development -We are looking for contributors! - -Building from the source -``` -make install-go -``` -Compile a new `commit0` binary in the working directory -``` -make build -``` - -Now you can either add your project directory to your path or just execute it directly -``` -mkdir tmp -cd tmp -../commit0 create test-app -cd test-app -../../commit0 generate -c commit0.yml -``` - -To run a single test for development -``` -go test -run TestGenerateModules "github.com/commitdev/commit0/internal/generate" -v -``` +- [UX Design Components][ux] -### Building locally -As there are some dependencies it will be easier to use this tool within the provided image, clone the repo and then run `make build-docker-local`. -The best way then to use this is to add an alias, then you can use the CLI as if it was installed as usual on your machine: -`alias commit0='docker run -it -v "$(pwd):/project" commit0:v0'` + +[drive]: https://drive.google.com/drive/u/0/folders/1_b8qqy5iN5envfWvIYPW5SNR_ektt5kJ +[ux]: https://docs.google.com/document/d/1yQ4bZ5z0slL9PpmduItEiCXYKIor0nX-nnGT3J-JOFw +[old]: https://github.com/commitdev/zero-old