Subversion Commit Guidelines
The idea of this document is to give the RepRap team a common set of guidelines about what to do before comitting changes into our shared Subversion repository trunk. Nothing is cast in stone, the idea is that a few simple checks can save frustrating others in the team and having to back out changes later.
Guidelines are listed for all subsystems, and then for each subsystem in turn. Guidelines are listed in (roughly) order of priority, most important first.
General Commit Guidelines
- The overall principle is that the main "trunk" codebase in Subversion should "basically work" when a fresh checkout is done. At all times.
- Do not commit changes when you are really really tired, or otherwise less than normally mentally alert for any reason.
- Commit source files, not resulting binary files (.java not .class, .c not .hex, .aoi not .stl, and so forth)
- If you are doing some really "out there" experimenting, please create yourself a private branch and use that, then merge your set of changes when your experiments turn out great.
- Avoid committing "dot files" (files with names beginning with a period) unless there is very good reason to do so. Such files are hidden, and so may not be noticed by others in the team once checked out, leading to confusion.
- If you have not already read the Subversion Book please try to at least skim it. Failing that, just the first four (4) chapters is a great start. Knowing what Subversion can do lets all of us use it more effectively.
Host Software Commit Guidelines
- Make sure the host software compiles -- cd ~/workspace/Reprap ; ant clean jar
- Make sure the resulting host software runs -- cd ~/workspace/Reprap ; ant clean run
- If practical, ask someone else to try the software with your changes in it. They may quickly find some little thing you overlooked, because everyone uses a software package slightly differently.
- Make sure the resulting host software talks to a UCB. This assumes you have a UCB to test with.
- Make sure the resulting host software is no worse for basic extruding than it was before your changes. This assumes you have a Reprap/Repstrap of some sort to test with.
- If your changes involved anything "unusual", including new directories, as soon as you have commited your changes, check out the whole host subtree into a new location and test it there -- cd ; mkdir ~/projects/testreprap ; cd ~/projects/testreprap ; svn co https://reprap.svn.sourceforge.net/svnroot/reprap/trunk/reprap/host Reprap ; cd Reprap ; ant clean run
Firmware Commit Guidelines
- Make sure the firmware compiles and builds all of the .hex files -- cd ~/workspace/firmware ; make clean ; make
- Make sure SDCC compiles and works (a minor pain because it takes several minutes) -- cd ~workspace/firmware ; make distclean ; make
- If practical, have someone else test your new firmware before committing. Email a .hex file to a friend, have them use it and report their results to you, or whatever it takes. This can find simple issues you didn't spot yourself because of your own unique system configuration.
Electronics Commit Guidelines
- Make sure the changes made are consistent (schematic, PCB layout, silkscreen, ...)
- If practical, have someone else test your changes (build a revised PCB, or whatever the change is) before committing them. This helps a lot in discovering simple mistakes you overlooked or assumptions you made.
Mechanics Commit Guidelines
- I have no real idea beyond creating a new/modified part and using it before committing the change. Mechanics people please suggest appropriate guidelines here
Room for Improvement
This document is not intended as a straitjacket to creativity. If its guidelines prevent you from being effective as a team member, speak out and suggest better ones. There is plenty of room for improvement here.
-- Main.JonathanMarsden - 11 Jun 2007