While Altium does not directly support Git for version control, we have devised a few workarounds to avoid any major issues. This document will describe the steps to for setting up and using Git for the hardware repository.
Basics
Revision Naming
To better track the changes made to our boards, we name each revision in the following manner:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
Rev X.Y |
Where X represents each change that requires a board to be fabricated again, and Y represents each change committed to your branch. For example, the first revision of any schematic will be Rev 1.0, and the first board produced will be Rev 1.Y. The second revision of this board that has to be fabricated will then have Rev 2.Y. Please make sure to include the revision number inside your commit messages for easier tracking.
Commit Messages
Commit messages are added when you commit your files to your branch. By including useful information, it will allow us to easier keep track of revisions, and revert to any earlier revisions if necessary. Your commit messages should follow a similar format as this
| Code Block | ||||
|---|---|---|---|---|
| ||||
<ELEC-JiraTicketNumber> <ProjectName> <Rev X.Y> <Brief description of what was changed in this commit, it should include enough information for anyone else on the team to understand what you're working on> |
Setting Up Git
It is recommended that you use Git Bash for Windows. This provides a command line interface similar to a Linux or Unix based system. The following steps should help you clone our repository to your local folder.
...
Now you should have a copy of the repository on your local computer. This will then be the bases for any changes that you make.
Git Workflow
Branches
Branches allow us to work on projects in parallel. There are two types of branches, master and feature branches. While working on your project, you should be working within your own feature branch only. While within this branch, you may commit as many times as you'd like. It is recommended that you commit whenever you're done working with it, or after making any major changes. This will allow you to easily revert to an earlier version if needed. When the board is complete and reviewed at a board review session, you may then push this branch to masters. Otherwise, you should never commit directly to master.
...
| Code Block | ||
|---|---|---|
| ||
elec_##_projectname |
Creating and Working with Branches
1. Create a local branch
...
3. Then you can push all your local changes to the repository. For the first time. If you forgot to do this, git should remind you to do so.
| Code Block | ||
|---|---|---|
| ||
git push --set-upstream origin branch-name |
Afterwards, every time you push you only need to use.
| Code Block | ||
|---|---|---|
| ||
git push |
Now if you check on github, your changes should be present inside the branch you made.
Pull Requests
Pull requests are used to approve the changes that you made in your branch before merging that into the master branch. This will usually be done at a board review if it's a new PCB design. If it's a simple change that does not warrant a review, you may also contact a hardware lead on HipChat who can approve your PR.
Creating and Merging a PR
After making all your commits and making sure that it is ready to be merged into master, you may open a pull request on githubGitHub. Make sure that you change the default comment to something meaningful, it should have the following format:
...
Make sure that you tag the hardware leads as the Reviewers, and set any labels if you feel appropriate.
When your pull request is approved, you can then Squash and Merge the branch into masters. This can be done on the web client.