1. Getting started with the repository

This document is currently under development.

  • Contribution documentation may not be required at this point.

OCAH development is hosted on GitHub under the Tenstorrent organization. Clone the public repository and use standard GitHub workflows for issues, pull requests, and code review.

Development can proceed on either macOS or Linux. Open-source tools work on both platforms; commercial EDA tools such as VCS and Design Compiler are typically available on shared Linux build hosts when needed.

Follow these steps to get set up and started with development.

Changes are proposed from your own copy of the repository, called a fork, so you do not need write access to the main repository.

  1. Create a GitHub account if you do not already have one.

  2. Fork the repository: open https://github.com/tenstorrent/tt-oca-harness and select Fork. GitHub creates tt-oca-harness under your own account.

  3. Clone the repository and initialise its submodules, as described in Environment Setup (Steps 1 and 2). The clone’s origin remote is the main repository.

  4. Let Git push to GitHub on your behalf. Install the GitHub CLI and run gh auth login, choosing HTTPS when asked.

  5. Add your fork as a second remote, replacing <your-username>:

    git remote add fork https://github.com/<your-username>/tt-oca-harness.git

  6. Create a feature branch from the latest main (see below for branch management):

    git fetch origin
git checkout -b <your-branch> origin/main

  7. Commit your work and push the branch to your fork:

    git push -u fork <your-branch>

  8. Open a pull request from that branch to main of tenstorrent/tt-oca-harness (see Creating a Pull Request). GitHub offers a Compare & pull request button on the repository page after the push.

Contributors who have write access to the main repository can skip the fork and push the branch to origin instead.

To clone over SSH instead of HTTPS, add your key to GitHub and use git@github.com:tenstorrent/tt-oca-harness.git as the URL, or switch an existing clone with git remote set-url origin <ssh-url>.

2. Development Flow

We strive for a development process that balances agility and clarity. To that end, we use the following conventions and processes:

2.1. Management of Main branch

Direct commits to main are not allowed. All changes must come through a PR. The main branch will be protected and no direct pushes are allowed.

  • Development of each feature should happen on its own, dedicated branch

  • A GitHub issue should be associated with the feature where possible, to facilitate discussion and review.

  • The main branch is the target for all feature PRs.

  • All PRs targeting main must pass a battery of basic smoke tests automatically run by the GitHub CI before a merge is allowed. Early in the project, there may not be meaningful tests, but these will be added as the project matures.

  • The main branch should be kept 'working' at all times, meaning that every version should be useful for continued development and testing. Developers should be able to pull the latest main branch and run the code without major issues.

2.2. Management of Release branches

Direct commits to release branches are not allowed. All changes must come through a PR.

  • When a release is close to ready a release branch is created from main and named for that minor release, for example v1.2.x. This branch is used to finalize the release, for example by updating documentation and fixing last-minute bugs.

  • All changes to the release branch are based on PRs with GitHub issues targeting the release branch. If these changes also apply to main, then a PR should be created against those branches as well.

  • All changes targeting the release branch must pass a battery of basic smoke tests automatically run by the GitHub CI before a merge is allowed as well as additional release specific tests.

  • All changes to the release branch are also applied to main

    • This means that the release branch is not merged back into main when the release is finalized. A trial merge can be done to ensure that all relevant changes are applied to main, but this is not strictly necessary.

  • When the release is finalized, the release branch is tagged with the release version.

  • Patch releases are cut from that same branch. v1.2.1 is a patch on v1.2.0. Readers can stay on the branch for later compatible fixes without moving to a new minor or major release.

2.3. Pull Requests

All changes, however small, must go through a pull request and be reviewed before being accepted into the release codebase.

A pull request (PR in GitHub terminology or MR, merge request, in GitLab terminology) is GitHub’s process of controlled merging between branches.

A pull request is a proposal to merge code changes from one branch into another (generally the main codebase). It lets developers ask team members to review, discuss, and approve updates before adding them to the released project.

Code changes not strictly related to the target feature, major change or issue should go into a separate PR. We make use of this to document changes to the codebase and facilitate code review.

A pull request (PR) should contain all the code changes required to address an issue, or all the code changes leading to the implementation of a new feature or a major change in the design. At the same time, a PR should be as small as possible to simplify and speed up the review process. It may make sense to break down larger contributions into multiple, self-contained PRs.

For bug fixes - a single PR is ideal to fix a single bug.

2.3.1. Creating a Pull Request

Open a pull request against main. There is a default template which asks for:

  • Summary — optional. What changed and why

  • Test plan — optional. Leave blank or write N/A if nothing was run

  • Closes — Add Fixes #N if this PR should close issues on merge (or pick them under Development). Delete this section if no issues are closed by this PR.

  • Notes — optional; delete if unused

CI does not require those sections. Project taxonomy lives in issues, not PRs. Pull requests are typically reviewed weekly.

2.3.2. Pull Request Guidance

  • Keep pull requests focused; unrelated changes belong in separate PRs.

  • Write clear commit messages that explain why a change is made.

  • Ensure relevant builds and checks pass before requesting review.

2.4. Continuous Integration

All changes to the source code are tested thoroughly in a continuous integration system.

Tests run automatically when changes are proposed for inclusion by submitting a pull request, and on the master branch after changes are merged. Changes which fail automated test cannot be submitted. This ensures that the source code meets certain quality criteria at all points in time, as defined by the tests which are executed.

2.5. Generated Content

Content automatically generated from source should not be tracked with Git. Makefiles and scripts should generate this content on-demand as part of build and simulation flows. Tracking generated content has many downsides including:

  • Repository bloat from constantly changing generated content. This is especially true when binary files are added.

  • Unintended inconsistencies between source and generated content. For example incorrect code could go to tapeout because a designer forgot to run the RTL code generation script before checking in critical source script changes. Missing content is preferable to incorrect content.

  • Unnecessary and confusing merge conflicts that may not be resolved properly, potentially leading to the same sort of design errors mentioned above.

There are exceptions where tracking generated content would be advisable, including:

  • Published specs and documentation generated from source for viewing directly from GitHub.

We can consider setting up Git LFS to track large binary content if necessary.

2.6. Versioning

Releases follow semantic versioning 2.0.0. A release tag is vMAJOR.MINOR.PATCH.

  • MAJOR — the release can break compatibility with the previous major release.

  • MINOR — the release adds functionality and stays compatible with the same major release.

  • PATCH — the release fixes defects and stays compatible with the same major and minor release.

v0.5.1 is a patch on v0.5.0. It is the same minor release, with compatible fixes. A pre-release label or build metadata can follow the version, as semver allows.

2.7. Conventions, Linting and CI

For details on Coding Styles and Conventions, see Guidance.

For details on linting and CI, please see Workflows.

3. Tracking Tasks and Bugs with GitHub

3.1. Working with Issues

Development tasks are managed using GitHub issues. GitHub supports issue hierarchy, so Issues may have parent and child issues. This allows grouping of related Issues which contribute to an overall goal.

Labels are a valuable tool to group related tasks. Care should be taken not to create too many new labels. Always check first if there is an existing label to cover the topic on which you are working.

3.2. Working with Milestones

Milestones may be used to indicate a release point where a number of changes will be available. Assigning issues to milestones allows tracking of progress towards the overall goal. Completion of milestones may trigger design reviews or progress updates.

3.3. Working with Bugs

Issues can also be used to track bugs. Design, verification, and firmware engineers may file bug issues against the design. Bug issues should be assigned to the owner of the affected code, who may then reassign the issue as appropriate to manage the corrective work. More detail on raising bugs is found in the section on Defects.

3.4. How to reference issues in commit messages and PRs

Commits and PRs related to existing issues or PRs should reference those. References should always be accompanied by a brief summary of the outcome of the referenced discussion and how the current PR/commit/issue relates to that.

3.5. Who should respond to filed issues?

As a collaborative project, anyone who feels qualified to help is encouraged to get involved with issues. If you’re working outside your usual area of expertise it is polite to say so.

If you see an issue that might be of relevance for a particular team member, you are welcome to ping this person by commenting on the issue mentioning that person (e.g. “@githubname what do you think?”).