awslabs / aws-code-habits

A library with Make targets, Ansible playbooks, Jinja templates (and more) designed to boost common software development tasks and enhance governance.

AWS Code Habits

A library with Make targets, Ansible playbooks, Jinja templates (and more) designed to boost common software development tasks and enhance governance.

Installing AWS Code Habits

Table of Contents

• Getting Started

• Prerequisites

• Usage

• How-Tos

  • How to initialize pre-commit config
  • How to maintain documentation
  • How to expand Habits commands

• Testing

Getting Started

AWS Code Habits was developed to be used as a git submodule.

On a terminal, on your project's root directory, execute one of the following commands:

git submodule add --name habits -b main https://github.com/awslabs/aws-code-habits.git habits

This will clone AWS Code Habits on a folder named habits and track against the main branch. Now, you will need to create, or add to your existing, Makefile.

export WORKSPACE=$(shell pwd)
export HABITS = $(WORKSPACE)/habits

include $(WORKSPACE)/tools.env # pin the version of your tools

include $(HABITS)/lib/make/*/*.mk
include $(HABITS)/lib/make/*.mk

Remember, next time you need to clone your repository, you will need to include --recurse-submodules parameters.

git clone --recurse-submodules ...

If you already cloned the project and forgot --recurse-submodules, you can combine the git submodule init and git submodule update steps by running git submodule update --init. To also initialize, fetch and checkout any nested submodules, you can use the foolproof git submodule update --init --recursive. - Git Tools Submodules

Check the scripts directory, if you want to automate the initialization and installation of AWS Code Habits.`

Prerequisites

A list of things you need, or how to install them.

At this stage, we are only supporting Linux (Ubuntu) environments (which can be obtained via WSL (Windows) or DevContainers (Mac/Linux/Windows))

• Python 3 - Whether you're new to programming or an experienced developer, it's easy to learn and use Python.
• Pip - pip is the package installer for Python.

Usage

make [tab][tab]

make help

For more information about each Make targets available.

How-Tos

Below you can learn

How to initialize pre-commit config

make pre-commit/init

To run all pre-commit rules in all files, simply run:

make pre-commit/run

How to maintain documentation

1. First initialize all documentation files:

make doc/init

This will create a folder named doc/ in the root directory of your project and create a file named habits.yaml inside of it.

2. Modify the contents of doc/habits.yaml accordingly and execute:

make doc/build

3. README.md will be rendered.

How to expand Habits commands

You can use Habits to meet your needs, in your Makefile you can add the following to ensure code and documentation hygiene:

.PHONY: hygiene
hygiene: doc/build pre-commit/run

Another example, if you want to perform several tasks with AWS CloudFormation:

.PHONY: hygiene
hygiene: aws/cloudformation/hygiene

.PHONY: plan
plan: aws/cloudformation/create-change-set

.PHONY: discard
discard: aws/cloudformation/delete-change-set

.PHONY: apply
apply: aws/cloudformation/execute-change-set

Testing

To perform habits checks:

make habits/check

References

• GNU Make - GNU Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files.
• Windows Subsystem for Linux (Ubuntu) - WSL enables you to use Linux tools, like Bash or Grep, completely integrated with Windows tools, like PowerShell or Visual Studio Code, with no need to dual-boot.
• Visual Studio Code - Visual Studio Code is a code editor redefined and optimized for building and debugging modern web and cloud applications.
• VSCode Remote Development Extension Pack - An extension pack that lets you open any folder in a container, on a remote machine, or in WSL and take advantage of VS Code's full feature set.
• Git Submodules - Submodules allow you to keep a Git repository as a subdirectory of another Git repository.
• Docker - The fastest way to containerize applications
• Visual Studio Code - Visual Studio Code is a code editor redefined and optimized for building and debugging modern web and cloud applications.
• Visual Studio DevContainers - The Visual Studio Code Dev Containers extension lets you use a Docker container as a full-featured development environment.
• VSCode Remote Development Extension Pack - An extension pack that lets you open any folder in a container, on a remote machine, or in WSL and take advantage of VS Code's full feature set.
• Ansible - Ansible is an open source community project sponsored by Red Hat, it's the simplest way to automate IT.
• Jinja2 - Ansible uses Jinja2 templating to enable dynamic expressions and access to variables and facts.

License

This project is licensed under the MIT-0 License. See the LICENSE file.

Copyright

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

aws-code-habits's Issues

Newer tflint versions report errors

The error

 $ make terraform/init
Reading file .terraform-version 
Unable to write to: /usr/local/bin/terraform
Creating bin directory at: /home/vscode/bin
Creating directory for terraform binary at: /home/vscode/bin
RUN `export PATH=$PATH:/home/vscode/bin` to append bin to $PATH
Downloading to: /home/vscode/.terraform.versions
21019880 bytes downloaded
Switched terraform to version "1.5.7" 
Terraform v1.5.7
on linux_amd64
terraform fmt
terraform fmt -check=true
Command line arguments support was dropped in v0.47. Use --chdir or --filter instead.
make: *** [/workspaces/aws/habits/lib/make/tflint/Makefile:32: tflint/run] Error 1

The relevant part in the Makefile

tflint/run:
	@tflint .

• Version: release 1.4.0
• Local OS Version: Ubuntu 22.04.1 LTS
• Local chip architecture: x86
• Reproduces in: Local run