diff --git a/README.md b/README.md index 90e1e6b4..db12897f 100644 --- a/README.md +++ b/README.md @@ -47,14 +47,24 @@ CICD-Tools provides four consumables to end-user projects that together form the For more details on these components, please read the complete [Technical Overview](./markdown/OVERVIEW.md). -### Supported Project Types - -CICD-Tools supports the following types of projects: - -1. [cookiecutter](https://github.com/cookiecutter/cookiecutter) templates. - - Please see the [implementation documentation](markdown/project_types/COOKIECUTTER.md). -2. [poetry](https://python-poetry.org/) based projects, that may use Python, Shell or other languages. - - Please see the [implementation documentation](markdown/project_types/POETRY.md). +### Supported Project Installations + +CICD-Tools supports the following types of installs: + +1. Cookiecutter Template Installs + - Please see the [cookiecutter installation guide](markdown/project_types/COOKIECUTTER.md) for details on: + - installing CICD-Tools into cookiecutter templates + - setting up CI/CD for templates and spawned projects + - setting up pre-commit for templates and spawned projects +2. Standard Project Installs (Projects may use Python, Shell or other languages.) + - Please see the [standard installation guide](markdown/project_types/STANDARD.md) for details on: + - installing CICD-Tools into existing projects + - setting up CI/CD for existing projects + - setting up pre-commit for existing projects +3. Lightweight Project Installs (Projects may use Python, Shell or other languages.) + - Please see the [light installation guide](markdown/project_types/LIGHT.md) for details on: + - installing CICD-Tools into existing projects + - setting up pre-commit for existing projects ## License diff --git a/markdown/project_types/COOKIECUTTER.md b/markdown/project_types/COOKIECUTTER.md index 28ba66fa..d1e0f455 100644 --- a/markdown/project_types/COOKIECUTTER.md +++ b/markdown/project_types/COOKIECUTTER.md @@ -1,6 +1,8 @@ # CICD-Tools -## API Documentation for Cookiecutter Projects +This is documentation for an installation that sets up [cookiecutter](https://github.com/cookiecutter/cookiecutter) template CI/CD, [poetry](https://python-poetry.org/) and [pre-commit](https://pre-commit.com/) for your project. + +## Installation Into Cookiecutter Projects For [cookiecutter](https://github.com/cookiecutter/cookiecutter) projects, CICD-Tools actually provides two "layers" of CI coverage: diff --git a/markdown/project_types/LIGHT.md b/markdown/project_types/LIGHT.md new file mode 100644 index 00000000..1b2f2f36 --- /dev/null +++ b/markdown/project_types/LIGHT.md @@ -0,0 +1,67 @@ +# CICD-Tools + +This is documentation for a lightweight installation that sets up [poetry](https://python-poetry.org/) and [pre-commit](https://pre-commit.com/) for your project. + +## Light Installation Into Existing Projects + +If you have an existing project you'd like to use CICD-Tools with this is an excellent option for: +- Python or non-Python based projects +- projects where you would like to introduce [pre-commit](https://pre-commit.com/) hooks + +Although [pre-commit](https://pre-commit.com/) and [poetry](https://python-poetry.org/) are written in Python, they can also be used by projects in other languages (such as Golang or Ruby). + +There are language specific alternatives (such as [husky](https://github.com/typicode/husky) for Javascript) that may make a better choice for your specific project. However, [pre-commit](https://pre-commit.com/) may still be viable option in many cases if a Python interpreter is available. + +Currently, CICD-Tools is optimized to use [pre-commit](https://pre-commit.com/), but in the future other solutions may be supported. + +If you have an existing project that you'd like to add CICD-Tools to, the [install-light.sh](../../scripts/install-light.sh) script can automate a great deal of the process, but there will be manual changes required as well. + +Please read the documentation below to identify all the requirements. + +## Adding CICD-Tools to an Existing Project + +### Step 1. Ensure your Project Contains a `pyproject.toml` File + +[Poetry](https://python-poetry.org/) keeps all it's configuration in this file, and if you are managing conventional commits with [commitizen](https://pypi.org/project/commitizen/) you can bundle its configuration here as well. This allows you to consolidate both Python package management and tool configuration in one file. + +If you don't have an existing `pyproject.toml` it's fairly easy to setup: + +```bash +$ poetry init -q --dev-dependency=commitizen --dev-dependency=pre-commit +``` + +Depending on which CICD-Tools integrations you end up using, you may find it useful to explore formatting your `pyproject.toml` file with [tomll](https://github.com/pelletier/go-toml) and including some more advanced [commitizen](https://pypi.org/project/commitizen/) configuration. You can find examples of this in the [installer.sh](../../scripts/libraries/installer.sh) library file. + +Alternatively, the [install-light.sh](../../scripts/install-light.sh) setup script will automate this process for you giving you sensible, usable defaults. + +### Step 2. Add the CICD-Tools Bootstrap Layer + +In order to integrate with CICD-Tools, a minimal amount of configuration is required. + +#### Step 2a. Add the CICD-Tools Configuration Files + +Your project should contain the [.cicd-tools](../../.cicd-tools) folder at the root level. This is where global configuration is kept for CICD-Tools, and it's also where [Toolboxes](../../cicd-tools/boxes) are installed ephemerally during CI/CD. + +The `configuration` sub-folder needs to be populated with the [CICD-Tools configuration files](../../.cicd-tools/configuration) to facilitate and customize global CI tasks such as how Toolboxes are installed and how changelogs are generated. + +The [install-light.sh](../../scripts/install-light.sh) script will perform this installation for you. + +#### Step 2b. `.gitignore` Changes + +Once you've copied the above content, you should also add a line to your [.gitignore](../../.gitignore) file: + +```.gitignore +.cicd-tools/boxes/* +``` + +The [install-light.sh](../../scripts/install-light.sh) script will create this file if it doesn't exist or add this line if it does. + +### Step 3. Pre-Commit Hooks + +To make full use of CICD-Tools, you'll need to define some [pre-commit](https://pre-commit.com/) hooks. These hooks are used both for local development, and by the CI itself. + +Take a look at this example [.pre-commit-config.yaml](../../{{cookiecutter.project_slug}}/.pre-commit-config.yaml) file to get up and running quickly. + +If you have no [.pre-commit-config.yaml](../../{{cookiecutter.project_slug}}/.pre-commit-config.yaml) for your project the [install-light.sh](../../scripts/install-light.sh) script will create a basic one for you. + +Also keep in mind that each of the tools that you add may have their own configuration requirements. diff --git a/markdown/project_types/POETRY.md b/markdown/project_types/STANDARD.md similarity index 67% rename from markdown/project_types/POETRY.md rename to markdown/project_types/STANDARD.md index 474150ce..57f0de69 100644 --- a/markdown/project_types/POETRY.md +++ b/markdown/project_types/STANDARD.md @@ -1,16 +1,25 @@ # CICD-Tools -## API Documentation for Poetry Projects +This is documentation for a standard installation that sets up CI/CD, [poetry](https://python-poetry.org/) and [pre-commit](https://pre-commit.com/) for your project. -[Poetry](https://python-poetry.org/) is a Python package manager, and provides an excellent way to put [pre-commit](https://pre-commit.com/) under version control. [pre-commit](https://pre-commit.com/) itself is written in Python, but can be used by Non-Python projects (i.e. Javascript, or golang). +## Standard Installation Into Existing Projects -There are language specific alternatives such as [husky](https://github.com/typicode/husky) for Javascript that may make a better choice for your specific project. However, you may find that [pre-commit](https://pre-commit.com/) is a viable option. So, adding a [pyproject.toml](../../pyproject.toml) file may make sense- even for Non-Python projects. +If you have an existing project you'd like to use CICD-Tools with this is an excellent option for: +- Python or non-Python based projects +- projects where you would like to introduce [pre-commit](https://pre-commit.com/) hooks +- projects where you want to quickly setup CI/CD -If you have an existing project that you'd like to add CICD-Tools to, the [install-poetry.sh](../../scripts/install-poetry.sh) script can automate a great deal of the process, but there will be manual changes required as well. +Although [pre-commit](https://pre-commit.com/) and [poetry](https://python-poetry.org/) are written in Python, they can also be used by projects in other languages (such as Golang or Ruby). + +There are language specific alternatives (such as [husky](https://github.com/typicode/husky) for Javascript) that may make a better choice for your specific project. However, [pre-commit](https://pre-commit.com/) may still be viable option in many cases if a Python interpreter is available. + +Currently, CICD-Tools is optimized to use [pre-commit](https://pre-commit.com/), but in the future other solutions may be supported. + +If you have an existing project that you'd like to add CICD-Tools to, the [install-standard.sh](../../scripts/install-standard.sh) script can automate a great deal of the process, but there will be manual changes required as well. Please read the documentation below to identify all the requirements. -## Adding CICD-Tools to an existing Poetry Project +## Adding CICD-Tools to an Existing Project ### Step 1. Ensure your Project Contains a `pyproject.toml` File @@ -24,7 +33,7 @@ $ poetry init -q --dev-dependency=commitizen --dev-dependency=pre-commit Depending on which CICD-Tools integrations you end up using, you may find it useful to explore formatting your `pyproject.toml` file with [tomll](https://github.com/pelletier/go-toml) and including some more advanced [commitizen](https://pypi.org/project/commitizen/) configuration. You can find examples of this in the [installer.sh](../../scripts/libraries/installer.sh) library file. -Alternatively, the [install-poetry.sh](../../scripts/install-poetry.sh) setup script will automate this process for you giving you sensible, usable defaults. +Alternatively, the [install-standard.sh](../../scripts/install-standard.sh) setup script will automate this process for you giving you sensible, usable defaults. ### Step 2. Add the CICD-Tools Bootstrap Layer @@ -36,23 +45,23 @@ Your project should contain the [.cicd-tools](../../.cicd-tools) folder at the r The `configuration` sub-folder needs to be populated with the [CICD-Tools configuration files](../../.cicd-tools/configuration) to facilitate and customize global CI tasks such as how Toolboxes are installed and how changelogs are generated. -The [install-poetry.sh](../../scripts/install-poetry.sh) script will perform this installation for you. +The [install-standard.sh](../../scripts/install-standard.sh) script will perform this installation for you. #### Step 2b. `.gitignore` Changes -Once you've copied the above content, you should also add a couple of lines to your [.gitignore](../../.gitignore) file: +Once you've copied the above content, you should also add a line to your [.gitignore](../../.gitignore) file: ```.gitignore .cicd-tools/boxes/* ``` -The [install-poetry.sh](../../scripts/install-poetry.sh) script will create this file if it doesn't exist or add these lines if it does. +The [install-standard.sh](../../scripts/install-standard.sh) script will create this file if it doesn't exist or add this line if it does. ### Step 3. Add the Toolbox Fetching Action In order to interface with the [Toolbox Packaging System](../../cicd-tools/boxes), you'll need to add the [action-00-toolbox](../../{{cookiecutter.project_slug}}/.github/actions/action-00-toolbox/action.yml) [GitHub Action](https://github.com/features/actions) to your project. -The [install-poetry.sh](../../scripts/install-poetry.sh) script will perform this installation for you. +The [install-standard.sh](../../scripts/install-standard.sh) script will perform this installation for you. ### Step 4. Pre-Commit Hooks @@ -60,7 +69,7 @@ To make full use of CICD-Tools, you'll need to define some [pre-commit](https:// Take a look at this example [.pre-commit-config.yaml](../../{{cookiecutter.project_slug}}/.pre-commit-config.yaml) file to get up and running quickly. -If you have no [.pre-commit-config.yaml](../../{{cookiecutter.project_slug}}/.pre-commit-config.yaml) for your project the [install-poetry.sh](../../scripts/install-poetry.sh) script will create a basic one for you. +If you have no [.pre-commit-config.yaml](../../{{cookiecutter.project_slug}}/.pre-commit-config.yaml) for your project the [install-standard.sh](../../scripts/install-standard.sh) script will create a basic one for you. Also keep in mind that each of the tools that you add may have their own configuration requirements. diff --git a/scripts/install-cookiecutter.sh b/scripts/install-cookiecutter.sh index 9693bda9..99818804 100755 --- a/scripts/install-cookiecutter.sh +++ b/scripts/install-cookiecutter.sh @@ -1,6 +1,6 @@ #!/bin/bash -# Install the bootstrapped CICD-Tools system to an existing cookiecutter repository. +# Install CICD-Tools with CI/CD and pre-commit into an existing cookiecutter repository. # CICD-Tools Development script. diff --git a/scripts/install-precommit.sh b/scripts/install-light.sh similarity index 92% rename from scripts/install-precommit.sh rename to scripts/install-light.sh index ddad4ac6..6b19ef80 100755 --- a/scripts/install-precommit.sh +++ b/scripts/install-light.sh @@ -1,6 +1,6 @@ #!/bin/bash -# Install the default CICD-Tools precommit hook into an existing repository. +# Install CICD-Tools with pre-commit into an existing repository. # CICD-Tools Development script. @@ -89,9 +89,9 @@ _install_no_target_path() { } _install_usage() { - log "ERROR" "install-precommit.sh -- install the CICD-Tools pre-commit config to a repo." + log "ERROR" "install-light.sh -- install the CICD-Tools pre-commit config to a repo." log "ERROR" "---------------------------------------------------------------------------" - log "ERROR" "install-precommit.sh" + log "ERROR" "install-light.sh" log "ERROR" " -b [TOOLBOX VERSION]" log "ERROR" " -d [DESTINATION REPOSITORY PATH]" exit 127 diff --git a/scripts/install-poetry.sh b/scripts/install-standard.sh similarity index 93% rename from scripts/install-poetry.sh rename to scripts/install-standard.sh index 6a831350..7c06b667 100755 --- a/scripts/install-poetry.sh +++ b/scripts/install-standard.sh @@ -1,6 +1,6 @@ #!/bin/bash -# Install the bootstrapped CICD-Tools system to an existing poetry based repository. +# Install CICD-Tools with CI/CD and pre-commit into an existing repository. # CICD-Tools Development script. @@ -101,9 +101,9 @@ _install_no_target_path() { } _install_usage() { - log "ERROR" "install-poetry.sh -- install CICD-Tools to an poetry cookiecutter repo." + log "ERROR" "install-standard.sh -- install CICD-Tools to an poetry cookiecutter repo." log "ERROR" "-----------------------------------------------------------------------" - log "ERROR" "install-poetry.sh" + log "ERROR" "install-standard.sh" log "ERROR" " -b [TOOLBOX VERSION]" log "ERROR" " -g [GITHUB HANDLE]" log "ERROR" " -d [DESTINATION REPOSITORY PATH]"