update readme

.github/workflows/ruff.yml

@@ -8,11 +8,11 @@ jobs:
       - name: Install Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: '3.11'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install ruff
       # Update output format to enable automatic inline annotations.
       - name: Run Ruff
-        run: ruff check --output-format=github .
+        run: ruff check --output-format=github .

README.md

@@ -1,64 +1,143 @@
 # Webex Samples Template
 
-This is the Webex Samples repo template, which must be used for all code contributions. 
+This is the Webex Samples Template Repository, which must be used for all new code contributions. The Webex Samples Template is a standardized framework that provides contributors to the Webex Samples organization with a consistent and organized approach to creating code contributions. By using the template, contributors can create new repositories that are independent of the original repository's commit history, making it easier to track changes and maintain a clean codebase. The template also includes a sample README and linting tools for standardized code samples. Utilizing the template streamlines the contribution process and ensures consistency across the Webex Samples organization, benefiting contributors and maintaining a well-organized codebase.
 
-Using templates varies from directly forking a repo. The commit history is cleaned, and there is no link to the original repository. This will give your new repository all the framework needed but without the history or link to other repos. It will be easier to track your changes, and your work will not be tied to the repository’s other forks. 
+## Table of Contents
 
-To use this template, [follow these directions to create your new repo from the template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). Add your project code to the new repo. Then, reach out to Adam Weeks(adweeks) or Ashton Jordan (ashjorda) to have your new repo added to this Github Organization. All newly created repos are set to private by default. Once all Github actions have passed, and your repo is complete, contact to Adam or Ashton for review to make the repo Public. 
-
-This template repo also contains a sample README, that outlines sections you should include in your README to help properly describe the repo's contents. 
+- [Purpose of the Template](#purpose-of-the-template)
+- [Usage](#usage)
+- [Github Actions](#github-actions)
+- [Installing Prettier via npm (Local Machine)](#installing-prettier-via-npm-local-machine)
+- [Installing and Running Ruff Python Linter](#installing-and-running-ruff-python-linter)
+- [Pre-Commit Hooks](#pre-commit-hooks)
+- [Skipping Hooks](#skipping-hooks)
+- [Thanks!](#thanks)
 
 ## Usage
 
-1. **Clone the repository**: First, clone this repository to your local machine using `git clone [email protected]:WebexSamples/Webex-Samples-Template.git`.
+Using template repos varies from directly forking a repo. The commit history is cleaned, and there is no link to the original repository. This will give your new repository all the framework needed but without the history or link to other repos. It will be easier to track your changes, and your work will not be tied to the repository’s other forks.
+
+To use this template, [follow these directions to create your new repo from the template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). Add your project code to the new repo. Then, reach out to Adam Weeks (adweeks) or Ashton Jordan (ashjorda) to have your new repo added to this Github Organization. All newly created repos are set to private by default. Once all Github actions have passed, and your repo is complete, contact Adam or Ashton for review to make the repo public.
+
+This template repo also contains a sample README (this file), that outlines sections you should include in your README to help properly describe the repo's contents. Additionally, you can utilize the [Standard Readme](https://github.com/RichardLitt/standard-readme) format for your README to ensure consistency and best practices.
 
-2. **Install dependencies**: Install prettier/autopep8 as per the below instructions under "GitHub Actions" section
+1. **Create the repository**: First, create your repo by [following these directions to create your new repo from the template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
+
+2. **Clone the repository**: Next, clone this repository to your local machine using `git clone`.
+
+3. **Install dependencies**: Install prettier/autopep8 as per the below instructions under "GitHub Actions" section to start linting your codebase.
 
 ## Github Actions
 
-This template uses GitHub Actions workflow to enforce commonly accepted coding practices across various file formats. We use [Prettier](https://prettier.io), and [AutoPep8](https://pypi.org/project/autopep8/) for these linting workflows. These workflows run on every pull request. And before merging is allowed, these workflows must pass. During these workflow checks, none of your code will be modified. These checks are commonly focused on spacing and proper tabbing.  
+This template uses GitHub Actions workflow to enforce commonly accepted coding practices across various file formats. We use [Prettier](https://prettier.io), and [AutoPep8](https://pypi.org/project/autopep8/) for these linting workflows. These workflows run on every pull request. And before merging is allowed, these workflows must pass. During these workflow checks, none of your code will be modified. These checks are commonly focused on spacing and proper tabbing.
+
+The GitHub Actions workflow plays a crucial role in maintaining code quality and consistency within the project. It automates the process of enforcing coding practices, ensuring that all contributions adhere to the established standards.
 
+Specifically, the workflow performs the following checks:
+
+1. **Prettier Formatting**: Prettier is a code formatter that helps maintain consistent code style across the project. The workflow uses Prettier to check if the code follows the defined formatting rules. If any formatting issues are found, the workflow will fail, indicating that the code needs to be properly formatted. Please review the [`prettier.yml`](.github/workflows/prettier.yml) file to see the configuration and settings for the Prettier action.
+
+2. **Ruff Linting**: Ruff is a Python linter that checks for coding style violations and automatically fixes them. The workflow utilizes Ruff to identify any style issues in Python code. If any violations are detected, the workflow will fail, indicating that the code needs to be corrected. Please review the [`ruff.yml`](.github/workflows/ruff.yml) file to see the configuration and settings for the Ruff action.
+
+By running these checks on every pull request, the GitHub Actions workflow ensures that all contributions meet the required coding standards. This helps maintain a clean and consistent codebase, making it easier for developers to collaborate and understand each other's code. It also reduces the chances of introducing bugs or inconsistencies due to coding style variations.
+
+Overall, the GitHub Actions workflow is an essential part of the project's development process, promoting code quality and facilitating a smooth contribution workflow.
 
 ## Installing Prettier via npm (Local Machine)
 
 **Note: Prettier documentation link: (https://prettier.io/docs/en/install.html)**
 
 To format your code locally, run the following:
 
-1. Install prettier
-```bash
-npm install --save-dev --save-exact prettier
-```
+1. Checking what changes prettier would like to make on all the files within your repo. Before writing them:
 
-2. Checking what changes prettier would like to make on  all the files within your repo. Before writing them:
 ```bash
 npx prettier . --check
 ```
 
-3. To write the proposed changes, to ensure the prettier workflow passes. Use the following command:
+2. To write the proposed changes, to ensure the prettier workflow passes. Use the following command:
+
 ```bash
 npx prettier . --write
 ```
 
-## Installing AutoPep8 via pip (Local Machine)
+## Installing and Running Ruff Python Linter
 
-**Note: Autopep8 Documentation: (https://pypi.org/project/autopep8/)**
+**Note: Ruff Documentation: (https://github.com/astral-sh/ruff)**
+To lint your Python code locally, follow these steps:
 
-To format your code locally, run the following:
+1. Install ruff:
 
-1. Install autopep8
 ```bash
-pip install --upgrade autopep8
+pip install ruff
 ```
 
-2. Checking what changes prettier would like to make on  all the files within your repo. Before writing them:
+2. Run the ruff linter:
+
 ```bash
-autopep8 -r --diff --aggressive --aggressive .
+ruff .
 ```
 
-3. To write the proposed changes, to ensure the prettier workflow passes. Use the following command:
+3. To write the proposed changes, to ensure the Ruff workflow passes. Use the following command:
+
 ```bash
-autopep8 -r -i --aggressive --aggressive .
+ruff check --fix .
 ```
 
+## Pre-Commit Hooks
+
+This project utilizes Husky and lint-staged to automatically format code on pre-commit hooks.
+
+[Husky](https://github.com/typicode/husky) is a Git hook manager that allows you to run scripts at specific Git lifecycle events. In this project, Husky is configured to run a script before each commit.
+
+[lint-staged](https://github.com/lint-staged/lint-staged) is a tool that allows you to run linters on staged files. It helps ensure that only the relevant files are checked, improving performance. In this project, lint-staged is used in conjunction with Husky to format the code before it is committed.
+
+When you make changes to your code and try to commit them, Husky triggers the lint-staged script. lint-staged then runs the configured linters on the staged files, which in this case includes Prettier and Ruff. Prettier is responsible for formatting the code according to the defined rules, while Ruff checks for style violations in Python code.
+
+By using Husky and lint-staged, this project enforces code formatting and style consistency automatically, reducing the chances of introducing formatting issues or style violations. This ensures that the codebase remains clean and consistent, making it easier for developers to collaborate and maintain the project.
+
+To configure Husky and lint-staged in your own project, you can follow the steps below:
+
+1. Install Husky and lint-staged from the dev dependencies:
+
+```bash
+npm install
+```
+
+2. Commit your code!
+
+## Skipping Hooks
+
+We know that it might not be optimal to have your code checked for every commit (for example, work in progress commits that will be squashed later). For those occasions, skipping the git hooks might be necessary.
+
+### For a Single Command
+
+Most Git commands include a `-n/--no-verify` option to skip hooks:
+
+```sh
+git commit -m "..." -n # Skips Git hooks
+```
+
+For commands without this flag, disable hooks temporarily with HUSKY=0:
+
+```shell
+HUSKY=0 git ... # Temporarily disables all Git hooks
+git ... # Hooks will run again
+```
+
+### For multiple commands
+
+To disable hooks for an extended period (e.g., during rebase/merge):
+
+```shell
+export HUSKY=0 # Disables all Git hooks
+git ...
+git ...
+unset HUSKY # Re-enables hooks
+```
+
+## Thanks!
+
+We truly appreciate your contribution to the Webex Samples!
+
 Made with <3 by the Webex Developer Relations Team at Cisco