Git Workflow¶

Here’s a fun Git tutorial - this guide assumes familiarity.

Branching Model¶

This workflow is somewhere between legacy-Gitflow and the more modern trunk-based development, consisting of three “core” branches, two of which are build targets for a CI/CD pipeline.

Core branches summarized¶

Branch Name	Managed By	Description	Branch Protections	CI/CD Build Target
`main`	Team Lead	Used for releases; all commits are merged from “develop” and tagged	Only team lead can merge `develop` into `main`	Yes
`develop`	Team Lead	Branched off `main` at conception; primary merge target for `feature` / `debug` branches	All `feature` or `debug` merges gated behind pull requests to team lead	Yes
`feature` or `debug`	Developers	Branched off `develop` for adding new logic or debugging logic that finds its way into `develop`	None	No

Naming developer branches¶

Developers should adhere to the following convention when naming their branches:

<feature/debug>-<description>_<developer initials>

This convention ensures the workflow’s consistency and scales with team size.

Mitigating merge conflicts¶

Developers should be git pull/git fetch-ing the latest changes from origin/develop to their local develop and merging it into their feature/debug branches at least once a day (ideally in the morning), because it minimizes the likelihood of merge conflicts when issuing pull requests.

Making a pull request¶

When a developer is ready, they initiate a pull request to the lead, and the lead merges their feature branch into develop if the following conditions are met:

The developer ensured the FPGA design is in a buildable state (team lead can checkout the developer’s branch and confirm by running the build script for the synthesis tool)
The developer updated the documentation and can point to it (team lead can build and view it from the developer’s branch)

Visualizing the topology¶

        gitGraph
   commit
   branch develop
   checkout develop
   branch feature-my_feature_jr
   commit
   commit
   checkout develop
   merge feature-my_feature_jr id: "dev_CICD_build_1" type: HIGHLIGHT
   branch debug-made_mistake_jr
   commit
   checkout develop
   merge debug-made_mistake_jr id: "dev_CICD_build_2" type: HIGHLIGHT
   checkout main
   merge develop tag:"v1.0" id: "main_CICD_build_1" type: HIGHLIGHT

The CI/CD pipeline is configured to carry out the following tasks upon merges to develop or main:

Invokes the synthesis tool to run the FPGA design’s build script
Invokes Sphinx to generate the documentation
Invokes the simulator to run self-checking simulations (if any)

Note

Naturally, every merge junction on develop is guaranteed to be buildable as a result of this model, which makes those commits stable ground to “roll back” to in the event of a debug effort