Tools other than scopes that are just as useful

[Matador]

I was thinking about this, based on a thread I saw on Facebook.

For those who aren't using source-control software in their everyday lives, it is one of the most immensely useful tools in the programmers arsenal.  For me personally, I am a big fan of Git (and more specifically Github), as it solves multiple problems without much up-front investment.

Here are just a few of the benefits:
1) A method of backing up your projects:  services like GitHub allow you to centralize versions of your software, which means you have a backup performed every time time you 'git push'.  It also means it is trivially easy to upload and version all of your projects, then seamlessly pull those bits back down to other systems, each of which can be points of development.
2) A centralized way of tracking bugs:  GitHub provides bug tracking services as well, where you can write about things you think aren't working correctly, and then associate these ideas to code changes.  The issues can be 'todo's as well, to remind yourself of work that you need to do.
3) A seamless way of collaborating with other people:  CVS's allow you to work with multiple people and merge their changes in with yours on a line-by-line basis.
4) A way of tracking 'known-good' configurations of code:  this is one of the most useful features.  If you arrive at a point where things are working well, you can tag a release, and always give you an easy way to go back to that point with a few simple commands.
5) A way of testing ideas without easy ways of un-doing them:  this is also very useful:  you can create a branch in Git in about 100 ms.  You can test out an idea, and if it bombs, you can undue it back to a known state without error or ambiguity.  If you idea works out, you can merge your experiment back into a known good branch of development, and have access to all points in-between.

I know some reading are thinking "I'll never work with another person - what's the point?'  I'll answer with another question:  how many times have you got to a good place with things working well, then made a few slight changes, at which point it all fell apart, but then you were left wondering exactly what you had changed in order to cause the breakage.

Git (and most CVS tools) make it trivial to diff against the last known version, or any version that was seen in the past.  It will tell you exactly which files were changed and how, and you can undo them individually or just go back and try again with a simple command.

Most all CVS systems deal equally well with anything that is ASCII text based:  for example, I also version my BOM's along side code, as Eagle exports TXT based BOM's.  It means I can also see how BOM's have changed over time.

They can also work with binaries:  all of my Eagle projects are Git projects as well, so it means that I can version my schematics and layouts with tags as well.  I very often will version an Eagle project right after I get done drawing a schematic but before I start a board.  I also can maintain multiple versions of a board layout in parallel with Git, as I can so an SMD layout in one branch, and a PTH layout in another (for initial samples or debugging).  Then, all I have to do is switch to the appropriate branch before starting Eagle, and all of my edits are in the right place.

So I encourage everyone reading to start using these tools:  they will make you better programmers, and more productive over the long haul.  And then will save much hair-tearing if you mess something up, as you can go back to a sane state very quickly.  And if you couple it with an online service like GitHub, if your 7-year old drops your laptop, you can pull your projects to another system in a few seconds.

 

[Matador]

The second such tool is using annotated markup in your code in order to generate documentation.  The best systems I have used allow you to inject the markup/markdown right into the code, and make the documentation itself first-class citizens like the code they describe.

My favorite so far is Doxygen:  the syntax is easy to learn, and doesn't appear visually distracting when viewed next to the code.  The generated documentation is of high quality, and you can get some great features like automatic linkages to all places a function is called from, and whether or note code is orphaned (although most compilers are really good at this, like gcc with the -Os flag).

I also like to use Markdown for stand-alone documents, as it plays very nicely with CVS tools I mentioned above.  This works well for "Here's the architecture I am shooting for' kinds of documents, which live above source code, but may be a bit too high-level to include directly into the code.  Doxygen works with this as well, but those documents all stand alone by themselves.

 

[Andy Peters]

For those who aren't using source-control software in their everyday lives, it is one of the most immensely useful tools in the programmers arsenal.  For me personally, I am a big fan of Git (and more specifically Github), as it solves multiple problems without much up-front investment.

I'm a huge fan of proper source-code control, and I use it for everything. I use Subversion, and I have the Subversion server installed on a Mac at home. I'm not a fan of git, simply because it is overkill for single and small developer groups. But this is an implementation detail, and I encourage everyone to choose an SCC and use it.

I see a lot of documentation generated by Doxygen, and too much of it is less than useful. Of course, that's all on the person entering the Doxygen comments and tags, not the tool.

 

[fum]

I run an svn server on one of my hosted domains.  Allows me to not only source control, backup and share between my computers, but when I do outside collaboration, makes it easy to get people up and going, without a lot of files being sent in email.

I also edited the post hooks on the svn server, so that I get an email any time there is a commit.  It includes the comments, plus the diff, so I can track the revisions.

ju

 

[mattamatta]

Do any of you guys use the software-intended VCS tools for hardware design and other non-ascii binary stuff like that?
What do you use and how what kind of organization system do you end up with? (And I suppose the real question is how has it been working!)

 

[Matador]

Most VCS tools deal with binaries just fine.

In fact, since so many hardware tools save their output into structured text files (like XML), the VCS tools can even revision specific edit points within those files.

 

[Andy Peters]

Do any of you guys use the software-intended VCS tools for hardware design and other non-ascii binary stuff like that?
What do you use and how what kind of organization system do you end up with? (And I suppose the real question is how has it been working!)

Subversion works perfectly fine with binaries. I do not know about git. The only things to note with binary files are:

You can't diff between versions or between a modifications you've made to files in the working copy and the "pristine" (before editing) version. You can't see what changes were made by directly comparing the files; you need to rely on commit messages.

Also, you can't merge at will. This is important if more than one person is working on a binary file at a time. For example, say I'm working on something in a schematic, and so are you. We both make changes. I commit my change to the repository. Then he goes to commit, and subversion tells him that the repository has changed from what he was working on. This is called a "conflict." With text files, it's a simple matter of diff'ing the files with a file compare utility (I use FileMerge on the Mac, Beyond Compare on Windows works well too), looking at the differences, and merging changes manually. (Hopefully I've written a useful commit message so you can quickly understand my change!) With a binary file, though, as noted you can't diff so you can't merge your changes with mine. So it is common to use file locks to prevent someone else from changing a file while you're working on it. (Subversion doesn't use locks by default because merging text is easy. )

But, other than the merging issues, keeping binaries in the source-code control repo isn't a problem.

As for organization?  I organize the repo by project, and within a project there are the various design elements such as PCBs, microcontroller firmware, FPGA firmware, host software, and documentation. For each element, I use the standard Subversion "trunk/tags/branches" structure. (You can read the Subversion documentation for a discussion of this.)

 

[fum]

Do any of you guys use the software-intended VCS tools for hardware design and other non-ascii binary stuff like that?

Yes, everything goes into svn for me.  Spreadsheets, pcb layouts, CAD drawings, built binaries.  Even important emails or notes.

I always look at it as you want everything you need in order to remember/recreate the project into the repository.

When I hit a release point, add a tag for that release version, makes it easy to get back to that point if you need it, without having to wade through revisions.

the only way to organize it is in the way that makes the best sense to you, every project is different.