This chapter goes through the theory and practice of using source code management tool for FOSS projects, including obtaining source, build environment and tools, build systems, building, patching.
Actually, maybe it doesn't cover build systems. Maybe that's too complicated. Maybe that's a later chapter. Maybe we get as complicated as "don't break the build".
This is a conversation that you never want to hear.
"Oh no! The frobnitz is broken!"
"But it was working last week."
"I don't know what happened - was it the changes I made to the gorblewhonker?"
"Wait, I was putting that function in the gorblewhonker. I told you after class on Thursday, remember?"
"Shoot. Do you have last week's version with the working frobnitz? What's the difference?"
"Maybe. I don't know. Does this mean we have to redo all the improvements we've made to the blooglebox since then?"
"Argh."
Avoid conversations like this.
Use source code management.
Have you ever seen a folder that looked something like this?
<pre>
mycode-1.py
mycode-2.py
mycode-2-with-rachel's-changes.py
mycode-working.py
mycode-LATEST.py
</pre>
If so, you use version control. According to Wikipedia <ref>http://en.wikipedia.org/wiki/Revision_control</ref> version control "is the management of changes to documents, programs, and other information stored as computer files." You may also see this referred to as revision control, a VCS (version control system), or source control. We will use these words interchangeably throughout this chapter. Software is available to make this process easier.
There are three main types of source code management tools.
* version control - getting code, contributing changes to that code, and keeping track of the history of the changes.
* patch tools - how do you describe the differences between two versions of the same piece of code?
* build systems - how do you turn source code into something that actually works?
We'll go through each of them in turn.
Actually, I believe that this is three separate chapters.
There are two types of version control (and several choices for each type): centralized and distributed.
=== Centralised version control tools: cvs, subversion =
Centralized version control tools have One Master Copy of the code somewhere in a centralized (hence the name) location. These were the first types of version control systems; all the contributors to a project would get their code from the same server. To share their changes with each other, they would check it back into the same server. This is similar to having a shared directory on your computer where people can upload and download files.
Two common centralized version control tools are cvs and subversion. Both are still used by many projects.
=== Distributed version control tools: git, mercurial, bazaar =
http://en.wikipedia.org/wiki/Distributed_revision_control
http://betterexplained.com/articles/intro-to-distributed-version-control-illustrated/
(note: I may be mangling/oversimplifying the history of VCSes; I'd like to get someone who's actually worked on a VCS to chime in on this. --Mchua)
What happens if the central server of a VCS goes down? What happens if two developers are working side by side but don't have access to the central server (for instance, if they're offline)? How do people share code under these circumstances?
Enter distributed version control systems (DVCS). With a DVCS, developers can share code directly with each other without having to go through any particular centralized repository. In other words, each developer's repository is a separate fork (do we define this term somewhere?) of the code. With this power comes complexity.
Distributed version control tools can also be used in a centralized way, and often projects using a DVCS will designate one checkout as the "official" place where code changes (eventually) make their way up to. Along the way, however, they can be passed from developer to developer, branch to branch, fork to fork.
Common distributed version control systems include git, mercurial, and bazaar.
=== Choosing a version control tool =
Prefer centralized:
http://blog.ianbicking.org/distributed-vs-centralized-scm.html
Prefer distributed:
http://lwn.net/Articles/246381/
Everyone has their own opinion; every project has historical reasons for picking the VCS it did. If you do a web search for "distributed vs centralized version control" or similar, you'll see some of these dicsussions. If you're joining an existing project, use the VCS they use; if you're creating your own project, use the system you're most comfortable with. It's better to have any sort of version control than none at all, and you can always switch later (note: not sure if I actually want to put that last clause in there, since switching can be painful. Possible, though.)
=== Case study: why did large project $FOO change RCS? =
== Exercise: Downloading from a repo == Wes Dillingham has a good GIT into at http://teachingopensource.org/index.php/RIT/Git_introduction
You can use any version control system you want for this exercise.
* Install the VCS
* Look up a "checkout." What is a checkout? What is the command for a checkout in the VCS you've chosen?
* at some point we might want to put up a textbook
exercise server - I'd like to be able to set up repos for
svn, cvs, git, bzr, mercurial, etc so students can practice
checking code out, seeing commit histories, etc.
== Building the code ==
=== What is "building"? =
=== Makefiles and what they do =
=== GNU automake/autoconf and why they are useful =
=== Java build tools: Ant, Maven and friends =
== Exercise: Building Your Developer Workstation ==
The student should be able to build his or her own working checkout of the code, get it into a state where it builds and runs.
== Patching the code ==
Have you ever gotten an email that looked something like this?
<pre>
Jim,
I've attached our paper draft from last Tuesday, from before we
took out all the Tom Sawyer quotes that Prof. Henson actually wanted
us to leave in.
(this one should go right after the third paragraph)
"Like it? Well, I don't see why I oughtn't to like it. Does a boy get
a chance to whitewash a fence every day?"
(this one should go at the beginning of the second section, but after the picture)
"Boys, I know who's drownded--it's us!"
The last one is in the closing paragraph, but Terrence completely rewrote
that over the weekend so we have to figure out where to put the bit about
the picnic in the cave now, since it no longer fits in.
--Molly
</pre>
If so, you've made a patch. According to Wikipedia <ref>http://en.wikipedia.org/wiki/Patch_(computing)</ref>, a patch "is a piece of software designed to fix problems[1] with, or update a computer program or its supporting data." In the open source world, patches are usually text files that contain the differences between two versions of a piece of code. There are programs to help you automatically create and merge in those files.
=== What is a "patch"? =
=== What's the diff? Using RCS to figure out what's changed =
Sometimes you've changed something and you don't remember exactly what you changed. Sometimes somebody else changed something while you were working. This section will cover how to use your RCS tool to update to the latest revision set, and how to figure out what your diffs are.
=== How to create a simple patch =
Put it all together. How to change something locally and wrap it up into a patch.
=== Case study: Release Early, Release Often =
Why it's a bad idea to let large patches build up, and how to resist temptation, with copious examples of why not following RERO is a bad idea.
== Exercise: Creating a Patch ==
The student should create a simple patch and demonstrate that it applies properly against his or her chosen project.
== Committer access ==
=== What is a "committer"? =
=== When do you become a committer? =
=== What are the responsibilities of the committer? =
=== How to apply a patch to code and commit that patch =
== Exercise: Applying a Patch ==
(looking for useful references here so I don't become redundant)
* http://betterexplained.com/articles/a-visual-guide-to-version-control/ (opening example inspired by this, but it's not CC-licensed so we can't really remix it...)
* http://en.wikipedia.org/wiki/Revision_control
* http://en.wikipedia.org/wiki/List_of_revision_control_software
* http://www.gutenberg.org/files/74/74.txt (used in example - Tom Sawyer)
== Plans for moving this chapter forward ==
There has been error in communication with Booktype server. Not sure right now where is the problem.
You should refresh this page.