Merge pull request #105 from FullStackWithLawrence/next

Add a developer setup guide

.pre-commit-config.yaml

@@ -57,7 +57,6 @@ repos:
       - id: destroyed-symlinks
       - id: detect-aws-credentials
       - id: detect-private-key
-      - id: detect-private-key
       - id: end-of-file-fixer
       - id: forbid-new-submodules
       - id: trailing-whitespace
@@ -71,9 +70,6 @@ repos:
       - id: helmlint
       - id: terraform-validate
       - id: tflint
-    #  - id: shellcheck
-    #  - id: yapf
-    #  - id: markdown-link-check
   - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
     rev: v9.9.0
     hooks:

DEVELOPER_SETUP.md

@@ -0,0 +1,82 @@
+# Developer Setup Guide
+
+This repository contains three distinct projects, respectively, written in
+
+- [ReactJS](#reactjs-setup)
+- [Python](#python-setup)
+- [Terraform](#terraform-setup)
+
+In each case there are various technology-specific resources that you'll need to initialize in your development environment.
+
+## Repository Setup
+
+### GitHub Actions
+
+As a 1-person operation this project depends heavily on GitHub Actions to automate routine activities, so that hopefully, the source code is always well-documented and easy to read, and everything works perfectly. We automate the following in this project:
+
+- Code linting checks, during both pre-commit as well as triggered on pushes to the main branch
+- Unit tests for Python, React and Terraform
+- Semantic Version releases
+- version bumps from npm, PyPi and Terraform Registry
+
+### pre-commit setup
+
+This project uses pre-commit as a first-pass automated code review / QC process. pre-commit runs a multitude of utilities and checks for code formatting, linting, syntax checking, and ensuring that you don't accidentally push something to GitHub which you'd later regret. Broadly speaking, these checks are aimed at minimizing the extent of commits that contain various kinds of defects and stylistic imperfections that don't belong on the main branch of the project.
+
+Note that many of the pre-commit commands are actually executed by Python which in turn is calling pip-installed packages listed in requirements.txt located in the root of the repo. It therefore is important that you first create the Python virtual environment using `make api-init`. It also is a good idea to do a complete 'dry run' of pre-commit, to ensure that your developer environment is correctly setup:
+
+```console
+git pull
+make api-init
+pre-commit autoupdate
+pre-commit run --all-files
+```
+
+Output should look similar to the following:
+
+![pre-commit output](./doc/pre-commit.png)
+
+### Github Secrets setup
+
+The GitHub Actions automated processes depend on several credentials which are stored inside of Github Secrets. When creating pull requests, the GitHub Actions will use these secrets, [github.com/FullStackWithLawrence/aws-openai/settings/secrets/actions](https://github.com/FullStackWithLawrence/aws-openai/settings/secrets/actions), so there's nothing special for you to do.
+
+On the other hand, if you've forked this repo and are working on your own independent project, then you'll need to initialize each of these yourself.
+
+![Github Secrets](./doc/github-secrets.png)
+
+## Python Setup
+
+This project includes four distinct Python project, all located in api/terraform/python. They are located here because each of these projects is deployed to AWS Lambda, which in turn is being actively managed by Terraform.
+
+Note that this project leverages Dependabot for managing version numbers of all Python packages that are used in this project, regardless of where and how. Versions should always be up to date at the moment that you clone the repo. It therefore should never be necessary for you to manually bump PyPi package version numbers.
+
+```console
+git pull
+make api-init
+source venv/bin/activate
+```
+
+## ReactJS Setup
+
+Please refer to this detailed [ReactJS setup guide](./client/README.md) for how to use vite.js to initialize the ReactJS development environment.
+
+Note that this project leverages Dependabot for managing version numbers of all NPM packages that are used in this project, regardless of where and how. Versions should always be up to date at the moment that you clone the repo. It therefore should never be necessary for you to manually bump package.json version numbers.
+
+```console
+git pull
+make client-init
+```
+
+## Terraform Setup
+
+Please refer to this [Terraform setup guide](./api/README.md) for detailed instructions.
+
+Note that this project leverages Dependabot for managing version numbers of all Terraform modules that are used in this project. Versions should always be up to date at the moment that you clone the repo. It therefore should never be necessary for you to manually bump module version numbers.
+
+```console
+git pull
+cd api/terraform
+terraform init
+terraform plan
+terraform apply
+```

README.md

@@ -110,8 +110,11 @@ To get community support, go to the official [Issues Page](https://github.com/Fu
 
 ## Contributing
 
-We welcome contributions! There are a variety of ways for you to get involved, regardless of your background. In additional to Pull requests, this project would benefit from contributors focused on documentation and how-to video content creation, testing, community engagement, and stewards to help us to ensure that we comply with evolving standards for the ethical use of AI.
+We welcome contributions! There are a variety of ways for you to get involved, regardless of your background. In addition to Pull requests, this project would benefit from contributors focused on documentation and how-to video content creation, testing, community engagement, and stewards to help us to ensure that we comply with evolving standards for the ethical use of AI.
 
-Please review these [commit comment guidelines](./SEMANTIC_VERSIONING.md) for managing CI rules for automated semantic versioning as well as automated comment generation in CHANGELOG.md.
+For developers:
+
+- Please see the [Developer Setup Guide](./DEVELOPER_SETUP.md)
+- And also, please review these [commit comment guidelines](./SEMANTIC_VERSIONING.md) 😬😬😬 for managing CI rules for automated semantic versioning as well as automated comment generation in CHANGELOG.md.
 
 You can also contact [Lawrence McDaniel](https://lawrencemcdaniel.com/contact) directly.

run_pylint.sh

@@ -1,2 +1,3 @@
 #!/bin/bash
+# Called from pre-commit. Run pylint on all python files in the current directory
 python -m pylint "$@"