...

Rev X.Y

Where X represents each change changes that requires require a board new PCB to be fabricated again, and Y represents each change committed to your branchthat changes a component in the Bill of Materials. For example, if you created a new board then the first revision of any schematic version will be Rev 1.0. Once you receive the board and you realized that one of the parts should've been a 10k resistor instead of a 1k, you would change the schematic and the first board produced will be Rev 1.Y. The second revision of this board that has update the revision to Rev 1.1. Any changes that require a new board to be fabricated will then have be on 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

<ELEC<HW-JiraTicketNumber> <ProjectName> <Rev X.Y>
<Brief
description- ofWhat what was changed in this commit, it should include enough information for anyone else on the team to understand what you're working on> ? 

Library Changes
- List of schematic and library changes 

Your description 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. 

...

Note: Please make sure to name your branch in the following format, where ### is the JIRA ticket for the appropriate project 

elechw##_##_projectname

Creating and Working with Branches

...

git checkout -b <branch-name>

2. Make any changes to the files , then when you are ready to commitas necessary.  Then when you're ready to commit, check the files that have been changed to make sure you're only including things that you've intentionally changed. This command can only be run when you're in your local repository. 

git status

If all the files are what you expected, you can use the follow command to add all the files listed to your commit.  

git add . 

Otherwise, you may add each file seperately with git add. Often times you may have looked at another schematic or PCB in your local repository while working on your project and inadvertantly made changes. This can be easily fixed by running git add . in your project folder. It may look something like this: 

cd altium-lib
git add . 
cd ..
cd MSXII_PowerDistribution
git add . 
cd ..

3. If you are satisfied with the list of files added, you may now commit to your branch. Please make sure to tag your JIRA ticket (ELEC-###) in each commit. Also make sure that you have a meaningful message describing what you changed. You may also add a TODO to help you keep track of things if wished. The following command should only be used for simple (1-2 lines) commit messages. 

git commit -m'ELEC-### Commit message' 

Alternately, if you type 

git commit

a Vim window should open in your console. It should look something like this: 

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch elec_191_chaos_layout
# Your branch is up-to-date with 'origin/elec_191_chaos_layout'.
#
# Changes to be committed:
(List of files that were added, deleted, or modified) 

By pressing i for "insert", you can now add text in vim. The benefit of writing your commit message in vim is that it allows you to format multiple lines of comments easily. If you made any library changes, you should include them here as well. The more detailed your commit message is, the easier it is for others to understand what you've been working on. A sample commit message may be as follows. Note that any line with a # is not included in your commit message, and git will not allow you to commit without any a message. 

ELEC-191 Power Distribution Board Rev 2.1
- Modified schematic to include missed connection between Aux_IN and the LTC4417

Schematic Library: 
- Added CAP ALUM 100UF 20% 16V RADIAL
- Linked CONN 6POS ULTRAFIT 0.138" to its footprint in the footprint library

Footprint Library
- Added CAP ALUM 100UF 20% 16V RADIAL
- Added CONN 6POS ULTRAFIT 0.138" 

TODO: 
- Modify layout to include the bulk capacitor
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch elec_191_chaos_layout
# Your branch is up-to-date with 'origin/elec_191_chaos_layout'.
#
# Changes to be committed:
(List of files that were added, deleted, or 

...

modified) 

After you've written your commit message, press ESC followed by :wq to exit vim and save the commit message. More commands in Vim may be found here

4. Then you can push all your local changes to the repository. For If you're pushing to the branch for the first time. If you forgot to do this, git should remind you to do somay prompt you to set the upstream branch. In that case, type exactly what is prompted. 

git push --set-upstream origin branch-name

...

Now if you check on github, your changes should be present inside the branch you made. 

Copying library files to another branch for PRs

Sometimes if multiple people are working with the library, it may be more convenient to put your changes in a separate branch and commit that. This allows you to break up your pull requests into smaller changes without constantly switching branches. After pushing your changes to their old branch, create a new branch and switch to that branch with this command

git checkout -b <new-branch-name>
git checkout <old-branch-name> altium-lib/Schematic\ Diagrams.SchLib
git status (You should now see the SchLib file under modified) 
git commit -m'List all the library changes' 
git push --set-upstream origin <new-branch-name>  

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 on Slack who can approve your PR.

Creating and Merging a PR 

...

When your pull request is approved, you can then Squash and Merge the branch into masters. This can be done on the web client. 

Git Diff Tool for the Schematic Library

Titus Chow has created a bash script that finds changes in the schematic library across two branches. It is recommended that you use Bash on Ubuntu on Windows for Windows 10.

1. Navigate to your local hardware repo with Bash on Ubuntu on Windows

cd mnt/c/Users/<username>/<repo location>

 Dealing With Merge Conflicts

Scenario 1: Library in the branch supersedes the changes in master

This scenario occurs if you master has been updated since the last time you pulled from it, and you made changes on top of that. By choosing "ours", you replace the file in master with the file on your branch. This means that your branch must contain any other changes that were made on master, in addition to your own changes. 

Example: 

We have 3 branches: master, A, and elec_191_chaos_layout. A has been merged into master already, with a small change to the PCB library in the form of a deleted pad. elec_191_chaos_layout has the same pad deleted, and a few other additions/changes made to other components. To merge elec_191_chaos_layout into master, we first run merge, and then check status: 

$ git merge master
warning: Cannot merge binary files: altium-lib/Schematic Diagrams.SchLib (HEAD vs. master)
warning: Cannot merge binary files: altium-lib/Footprints.PcbLib (HEAD vs. master)
Auto-merging altium-lib/Schematic Diagrams.SchLib
CONFLICT (content): Merge conflict in altium-lib/Schematic Diagrams.SchLib
Auto-merging altium-lib/Footprints.PcbLib
CONFLICT (content): Merge conflict in altium-lib/Footprints.PcbLib
Automatic merge failed; fix conflicts and then commit the result.


$ git status
On branch elec_191_chaos_layout
Your branch is up-to-date with 'origin/elec_191_chaos_layout'.
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Changes to be committed:

        modified:   MSXII-Controller-Board/Controller-Board-Rev3.PcbDoc
        modified:   MSXII-Controller-Board/Controller-Board.PrjPcb
        modified:   MSXII-Controller-Board/Controller_Board_Main.SchDoc
        modified:   MSXII-Controller-Board/Controller_Board_Power_Supply.SchDoc
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/Controller-Boa
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/ControllerBoar
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/Design Rule Ch
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/Design Rule Ch

Unmerged paths:
  (use "git add <file>..." to mark resolution)

        both modified:   altium-lib/Footprints.PcbLib
		both modified:   altium-lib/Schematic Diagrams.SchLib

From this, we can see that the change common to both elec_191 and master is the Footprints library and Schematic Diagrams library. We want to choose our libraries over the one in master: 

$ git checkout --ours altium-lib/.
$ git add .

Then run status again: 

$ git status
On branch elec_191_chaos_layout
Your branch is up-to-date with 'origin/elec_191_chaos_layout'.
All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:

        modified:   MSXII-Controller-Board/Controller-Board-Rev3.PcbDoc
        modified:   MSXII-Controller-Board/Controller-Board.PrjPcb
        modified:   MSXII-Controller-Board/Controller_Board_Main.SchDoc
        modified:   MSXII-Controller-Board/Controller_Board_Power_Supply.SchDoc
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/Controller-Boa
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/ControllerBoar
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/Design Rule Ch
        new file:   MSXII-Controller-Board/Project Outputs for Controller-Board/Design Rule Ch

Then you can commit, and push as normal. After this, you should now be able to squash and merge on GitHub using the web interface.