Merge branch 'main' into rc-v1.2.0

CONTRIBUTING.md

@@ -1,51 +1,129 @@
-# Contributing to TT-STUDIO
+# **Contributing to TT-STUDIO**
 
-Thank you for your interest in this project! We want to make contributing as easy and transparent as possible.
+Thank you for your interest in this project! We aim to make the contribution process as easy and transparent as possible.
 
-If you're interested in making a contribution, please familiarize yourself with our technical [contribution standards](#contribution-standards) outlined in this guide.
+If you’d like to contribute or have suggestions , please familiarize yourself with technical [contribution standards](#contribution-standards) outlined in this guide.
 
-Next, request the appropriate write permissions by [opening an issue](https://github.com/tenstorrent/tt-studio/issues/new/choose) for GitHub permissions.
+---
 
-All contributions require:
+## **Contribution Requirements**
 
-- An issue:
-  - Please file a feature request or bug report under the Issues section to help get the attention of a maintainer.
-- A pull request (PR).
-- Your PR must be approved by the appropriate reviewers.
+- **Issue Tracking:**
 
-## Contribution Standards
+  - File a feature request or bug report in the Issues section to notify maintainers.
 
-### Code Reviews
+- **Pull Requests (PRs):**
+  - All changes must be submitted via a PR.
+  - PRs require approval from the appropriate reviewers before merging.
+
+---
+
+## **Contribution Standards**
+
+### **Code Reviews**
 
 We actively welcome your pull requests! To ensure quality contributions, any code change must meet the following criteria:
 
 - A PR must be opened and approved by:
   - A maintaining team member.
   - Any codeowners whose modules are relevant to the PR.
-- Run pre-commit hooks.
-- Pass all acceptance criteria mandated in the original issue.
-- Pass the automated GitHub Actions workflow tests.
-- Pass any testing requirements specified by the relevant codeowners.
+- Run **pre-commit hooks**.
+- Pass all **acceptance criteria** mandated in the original issue.
+- Pass the **automated GitHub Actions workflow tests**.
+- Pass any **testing requirements** specified by the relevant codeowners.
+
+---
+
+## **Git Branching Strategy Overview**
+
+### **1. Main Branches**
+
+- **`main`** – Holds production-ready tagged code.
+
+  - **Rules:**
+    - No force pushes.
+    - Requires **rebase and merge** or **squash and merge** from a release cut branch.
+
+- **`dev`** – The central branch where all feature branches are merged and validated before preparing a release branch.
+  - **Rules:**
+    - No force pushes.
+    - Requires **squash merge** from a feature branch.
+
+---
+
+### **2. Feature Development Workflow**
+
+#### **Development Process**
+
+- **Feature Branches:**
+
+  - Created from `dev`.
+  - **Naming convention:** `dev-name/feature` or `dev/github-issue-number`.
+    - Example: `dev-john/new-feature` or `dev-john/1234`.
+
+- **Merging to `dev`:**
+  - Once completed and reviewed, feature branches are **squash merged** into `dev` to maintain a clean history.
+
+---
 
-### Pull Request Guidelines
+### **3. Release Process**
 
-- All PRs must first be merged into the `staging` branch. We use a squash merge strategy for this, meaning that all the individual commits from a feature branch are combined into a single commit when merged. This simplifies the commit history, ensuring that the feature is tracked as a single change while keeping the repository clean and manageable.
+#### **Release Preparation**
 
-- When merging from `staging` into `main`, we do **not** use squashing. This ensures that the full commit history between these branches is preserved.
+- **Creating the Release Branch:**
 
-Please ensure that this process is followed when submitting PRs to keep the repository organized and maintainable.
+  - When `dev` is stable and ready for release, a **release cut branch** is created from `main`.
+  - **Naming convention:** `rc-vx.x.x` (e.g., `rc-v1.2.0`).
 
-### Versioning Standards
+- **Feature Inclusion:**
 
-To ensure consistency in versioning, we follow the principles of **semantic versioning**:
+  - Developers **cherry-pick** validated features from `dev` into the release branch.
+  - Test and resolve any **merge conflicts** as needed.
+
+- **Testing & Fixes:**
+  - The release branch undergoes **testing before deployment**.
+  - **Bug fixes and PR comments** follow the standard development flow and can be cherry-picked into the same release branch.
+
+---
+
+#### **Final Deployment**
+
+- After validation, the **release branch is merged into `main`** for production.
+- **At least two approvals** are required for merging to `main` to ensure quality.
+- Merging can be done via **rebase and merge** or **squash and merge** if multiple commits were cherry-picked.
+- The release is **tagged following semantic versioning** (e.g., `v1.0.0`).
+
+---
+
+### **4. Git Tagging**
+
+- **Tags are created in `main`** to mark production releases.
+- **Semantic versioning** (e.g., `v1.0.0`) is used to track different versions.
+
+---
+
+## **Versioning Standards**
+
+To ensure consistency, we follow **semantic versioning** principles:
+
+- **MAJOR**: Increment for **breaking changes** to backend or frontend APIs or functionality.
 
-- **MAJOR**: Increment for incompatible or breaking changes to backend or frontend APIs or functionality:
   - Removing or significantly altering existing features.
-  - Changing the current networking design.
-  - Altering backend API flows.
-  - Changing frontend API calls and/or redoing entire components.
+  - Changing the networking design.
+  - Modifying backend API flows.
+  - Redesigning frontend API calls or components.
+
+- **MINOR**: Increment for **new features** or capabilities that are **backward-compatible**.
+
+  - Example: Supporting new models like YOLOv4 or adding additional functionalities.
+  - If the current version is `1.2.3` and a new **minor** release is introduced, it becomes **`1.3.0`**.
+  - If additional patches are needed after `1.3.0`, the version will increment to **`1.3.1`**, **`1.3.2`**, and so on.
+
+- **PATCH**: Increment for **bug fixes and minor improvements** that are **backward-compatible**.
+  - If patches are applied to `1.2.3`, the next versions would be `1.2.4`, `1.2.5`, etc.
+
+---
 
-- **MINOR**: Increment when adding new features or capabilities in a backward-compatible manner:
-  - For example, supporting new models like YOLOv4 or adding new functionalities.
+## **Git Branching Strategy Flowchart**
 
-- **PATCH**: Increment for bug fixes and minor improvements that are backward-compatible.
+<img src="Git-management.png" alt="Git Branching Strategy" width="600" />

app/README.md

@@ -20,7 +20,7 @@ Environment variables are defined in `.env`, `.env.default` is a template you ca
 cp .env.default .env
 # edit JWT_SECRET
 vim .env
-```
+````
 
 Note: the backend runs inside a container, because of this it does not have access to the host file system directly to programmatically determine it's relative path.