pmcdi · JoshuaSiraj · Feb 10, 2025
diff --git a/docs/contributing/adding_content.md b/docs/contributing/adding_content.md
@@ -0,0 +1,105 @@
+# [Adding Content](#adding-content)
+
+## Introduction
+
+> This document will guide you through the process of adding a new page to the
+> handbook.
+
+!!! tip
+
+    The handbook is built using [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+    These tools also have extensive documentation and guides for contributing to a Mkdocs project.
+
+    Please refer to their respective documentation **first** for any questions you might have.
+
+## Adding Content to the Documentation
+
+The documentation is written in Markdown and can be found in the `docs` directory.
+
+Here are the steps to add new content to the documentation:
+
+### 1. Create a branch for your changes
+
+??? note "Note: Naming your branch"
+    A branch is a way to work on a new feature or bug fix without affecting the main branch.
+    The standard for this project is to use the following format:
+
+    ```console
+    $ <author-ID>/<purpose-of-branch>
+    OR
+    $ <author-ID>/<issue-reference>
+    ```
+    Where `<author-ID>` can be a GitHub username or an alias.
+
+    `<purpose-of-branch>` is a short description of the changes you are making.
+    `<issue-reference>` is the number of the issue you are working on.
+
+    For example:
+
+    ```console
+    $ jjjermiah/adding-getting-started-page
+    OR
+    $ jjjermiah/13-docs-finish-tutorial-for-page-review
+    ```
+
+To **create a new branch and switch to it**, run the following command:
+
+```console
+git checkout -b <branch-name>
+$ git checkout -b jjjermiah/adding-getting-started-page
+```
+
+If you already have a named branch, you can switch to it with the following command:
+
+```console
+git switch jjjermiah/adding-getting-started-page
+```
+
+### 2. Add your new content to the `docs` directory
+
+??? question "How do I know where to create my file?"
+
+    This will create an empty Markdown file called `my_new_page.md` in the `docs/onboarding` directory.
+    The relative path to the `docs` directory, will be the link to your new page. <br>
+    i.e the link to your new page will be `<website-url>/handbook/onboarding/my_new_page/`
+
+Let's say you want to add a new page to the `Onboarding` section.
+You would add a new file to the `docs/onboarding` directory.
+
+```console
+$ touch docs/onboarding/my_new_page.md
+You should now see a new file at `docs/onboarding/my_new_page.md`.
+```
+
+To learn more about how to actually write content, see the [HandBook MkDocs Page][mkdocs] and
+[Handbook Markdown page][markdown].
+
+### 3. Preview your changes
+
+The following is a [`pixi task`](https://pixi.sh/latest/features/advanced_tasks/)
+that will start a local server and preview the documentation at `http://localhost:8000`.
+
+```console
+$ pixi run serve
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+...
+INFO    -  [08:55:05] Serving on http://127.0.0.1:8000/handbook/
+```
+
+You should see your changes appear at `http://127.0.0.1:8000/handbook/onboarding/my_new_page/`
+
+### 4. Commit and push your changes to your branch
+
+```console
+git add .
+git commit -m "Add new getting started page"
+git push --set-upstream origin jjjermiah/adding-getting-started-page
+```
+
+### 5. Create a PR
+
+Create a pull request (PR) to merge your changes into the main branch.
+Request a review from a maintainer.
+
+See [the section on Reviewing a Contribution][reviewing-a-contribution] for more information.
diff --git a/docs/contributing/changelog.md b/docs/contributing/changelog.md
@@ -0,0 +1,5 @@
+# Framework Changes Over Time
+
+{%
+    include-markdown "../../CHANGELOG.md"
+%}
diff --git a/docs/contributing/conventional_commits.md b/docs/contributing/conventional_commits.md
@@ -0,0 +1,43 @@
+# [Convential Commits](#convential-commits)
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps us automate our release process and keep our commit history clean. 
+
+This style is mandatory for [merging pull requests][modify-the-commit-message-as-needed] on the handbook, but are recommended for all commits.
+
+The main points are summarized below, but you can read the full spec [here](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## Commit Message Format
+
+Each commit message consists of a **header**, a **body** and a **footer**. The header has a special format that includes a `<type>`, a `<scope>` and a `<summary>`:
+
+```
+<type>[optional scope]: <short summary in present tense>
+
+[optional body: explains motivation for the change]
+
+[optional footer(s): note BREAKING CHANGES here, and issues to be closed]
+```
+
+The `<scope>` of the header is optional and provides context for where the change was made. It can be anything relevant to your package or development workflow (e.g., it could be the module or function - name affected by the change).
+
+`<type>` refers to the kind of change made and is usually one of:
+
+- `feat`: A new feature.
+- `fix`: A bug fix.
+- `docs`: Documentation changes.
+- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
+- `refactor`: A code change that neither fixes a bug nor adds a feature.
+- `perf`: A code change that improves performance.
+- `test`: Changes to the test framework.
+- `build`: Changes to the build process or tools.
+- `ci`: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- `chore`: Other changes that don't modify src or test files
+
+Other types may be defined per project, but these are the most common.
+
+
+## Sources
+
+1. [Angular Commit Format Reference Sheet - Brian Clements](https://gist.github.com/brianclements/841ea7bffdb01346392c)
+2. [Origin of Angular Commit Style - AngularJS Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)
+3. [Py-Pkgs tutorial - Automatic version bumping using Angular Commit Style](https://py-pkgs.org/en/latest/development/commit-guidelines.html)
diff --git a/docs/contributing/images/better_pr_body.png b/docs/contributing/images/better_pr_body.png
diff --git a/docs/contributing/images/merge_commit.png b/docs/contributing/images/merge_commit.png
diff --git a/docs/contributing/images/squash-merge.png b/docs/contributing/images/squash-merge.png
diff --git a/docs/contributing/images/squash_merge.png b/docs/contributing/images/squash_merge.png
diff --git a/docs/contributing/images/submitting-issues.png b/docs/contributing/images/submitting-issues.png
diff --git a/docs/contributing/images/update_pr_info.png b/docs/contributing/images/update_pr_info.png
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -0,0 +1,80 @@
+# Contributing to the Framework
+
+*Thank you for your interest in contributing to the Responsible AI Framework!*
+
+This section will guide you through the process of setting up your
+development environment, installing dependencies, and building the documentation.
+
+## Contributing Principles
+
+### KISS - Keep It Simple, Stupid
+
+(or Keep It Short and Simple)
+
+- We strive to keep the handbook **focused** and **concise** to make it easy for anyone to understand
+- We **avoid unnecessary complexity**
+
+### DRY - Don't Repeat Yourself
+
+- Saves **time** and **energy**
+- If details already exist on another page or website, **link to it**, don’t copy paste
+- When making a page, remember it might get referred to somewhere else!
+
+## For Contributors
+
+Below are some common questions to help you find the right guidance for specific
+contributing tasks.
+
+### Where should I start if I want to contribute?
+
+If you’re new to contributing, start with the **[Prerequisites](prerequisites.md)**
+page to set up your environment and install necessary dependencies.
+
+---
+
+### How do I submit an issue for a problem I found?
+
+If you’ve identified an issue, refer to the
+**[Submitting Issues](submitting_issues.md)** page. <br> It provides details on
+how to use our issue templates and submit effective bug reports or feature requests.
+
+---
+
+### How can I add new content to the handbook?
+
+To learn about adding or editing content, check out the
+**[Adding Content](adding_content.md)** page. <br> This guide explains how to
+structure and format your additions to fit seamlessly into the handbook.
+
+---
+
+### What steps are involved in the review process?
+
+The **[Reviewing a Contribution](reviews.md)** page outlines the review process,
+including best practices for constructive feedback and steps for both reviewers
+and contributors.
+
+---
+
+### Where can I view all the changes made to the handbook?
+
+To see recent updates and changes to the documentation, visit the
+**[Changelog](changelog.md)** page for a record of all documented changes.
+
+---
+
+By following these resources, you'll have everything you need to contribute
+effectively to the Lab Handbook. If you have additional questions, feel free
+to reach out to the maintainers or submit a question through the
+**[Submitting Issues](submitting_issues.md)** page.
+
+---
+
+## For Maintainers
+
+### How do I prepare for releasing and deploying changes?
+
+Check out the [Release & Deployment](release_deployment.md) page to learn
+about our release procedures, automated workflows, and deployment to GitHub Pages.
+
+---
diff --git a/docs/contributing/prerequisites.md b/docs/contributing/prerequisites.md
@@ -0,0 +1,42 @@
+# [Prerequisites](#prerequisites)
+
+## [Installing Pixi](#installing-pixi)
+
+Pixi is a tool for managing conda environments and dependencies.
+To install Pixi, visit the [Pixi website](https://pixi.sh/latest/) and follow the
+instructions specific to your operating system.
+The [Pixi documentation](https://pixi.sh/latest/) is an extensive resource for
+learning how to use Pixi.
+
+Running the following command in your terminal should verify installation.
+
+```console
+$pixi --version
+pixi 0.34.0
+```
+
+## [Cloning the Repository](#cloning-the-repository)
+
+To begin, clone the repository to your local machine using the following command:
+
+```console
+$ git clone git@github.com:pmcdi/responsible-ai.git
+Cloning into 'responsible-ai'...
+....
+....
+....
+...
+$ cd responsible-ai
+```
+
+## Installing Dependencies
+
+Once you have cloned the repository, navigate to the project directory and
+install the dependencies:
+
+```console
+$ pixi install
+✔ The default environment has been installed.
+```
+
+This will install the dependencies specified in the `pixi.toml` file.
diff --git a/docs/contributing/release_deployment.md b/docs/contributing/release_deployment.md
@@ -0,0 +1,52 @@
+# Release and Deployment
+
+## Introduction
+
+The framework website is hosted on [GitHub Pages](https://pages.github.com/).
+This document provides a detailed overview of how the deployment and release
+processes work, ensuring a smooth and automated workflow.
+
+## GitHub Pages
+
+GitHub Pages is a service that allows you to host static websites directly
+from your GitHub repository.
+
+### How It Works
+
+Whenever changes are pushed to the `main` branch, a
+[GitHub Action](https://github.com/features/actions) is triggered to
+automatically build and deploy the website.
+
+You can view the build and deployment action at
+[this link](https://github.com/pmcdi/responsible-ai/blob/main/.github/workflows/build_docs.yml).
+
+The automated workflow includes the following steps:
+
+1. **Check Out the Repository**: The GitHub Action checks out the latest code
+   from the `main` branch.
+2. **Install Dependencies**: Dependencies specified in the `pixi.toml` file
+   are installed.
+3. **Build the Documentation**: The action builds the site using MkDocs and
+   the configurations defined in your project.
+4. **Deploy to GitHub Pages**: The compiled site is deployed to the `gh-pages`
+   branch.
+
+Once the `gh-pages` branch is updated, GitHub Pages will automatically publish
+the latest version of the website.
+
+## Releases and Versioned Documentation
+
+We leverage [Python Semantic Release](https://github.com/python-semantic-release/python-semantic-release)
+to automate the release process and manage versioned documentation,
+making it easier to maintain version control, changelogs, and multiple
+documentation versions.
+
+### How Releases Work
+
+When a pull request is merged into the `main` branch, a
+[GitHub Action](https://github.com/features/actions) triggers the release
+process.
+
+You can view the release automation action at
+[this link](https://github.com/pmcdi/responsible-ai/blob/main/.github/workflows/semantic_release.yml).
+
diff --git a/docs/contributing/reviews.md b/docs/contributing/reviews.md
@@ -0,0 +1,51 @@
+# Reviewing a Contribution
+
+> **Note**: This document assumes there is an open Pull Request (PR) awaiting review.
+
+For more details, see the [GitHub Docs on Pull Requests with Required Reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews).
+
+## Introduction
+
+Once a contribution is submitted, a Pull Request (PR) must be created. Before merging into the main branch, the PR must undergo a review process.
+
+### Terminology
+
+- **Author**: The individual who submitted the contribution.
+- **Reviewer**: The individual reviewing the contribution.
+- **Maintainer**: The person responsible for merging the contribution after review.
+
+## Understanding a Review
+
+Reviews are discussions around the changes proposed in a PR. They allow for collaborative feedback, ensuring code quality and alignment with project standards.
+
+!!! tip
+
+    Anyone can review a PR, including those who are not maintainers!
+    If you see a PR from another author, and have suggestions for improvement,
+    feel free to leave a review.
+
+For further reading, refer to the [Official GitHub Documentation on PR Reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews).
+
+### Review Statuses
+
+When submitting a review, you can select from three statuses:
+
+1. **Comment**: Provide general feedback without explicitly approving or requesting changes.
+2. **Approve**: Indicate that the changes are acceptable, and approve merging the PR.
+3. **Request Changes**: Highlight issues that need to be addressed before the PR can be merged.
+
+## Requesting a Review for a Pull Request
+
+After creating a PR, you can request specific individuals or teams to review it.
+
+- Only members of the BHK Lab organization can request reviews from other members.
+
+For more information, check the [Official GitHub Documentation on Requesting a Pull Request Review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review).
+
+### Adding to an Existing Document
+
+If a document already exists, you can add to it. Check the bottom of the page for information on current authors.
+
+## Conclusion
+
+Effective reviews help ensure that contributions meet project standards, improve code quality, and facilitate knowledge sharing within the team. Whether you're an author, reviewer, or maintainer, understanding the review process is essential to contributing successfully.