Appendix A: Instructor Guide
Maybe you're an instructor, and you're using this textbook for your class. Maybe you're a self-learner, and you're walking through this textbook yourself. Either way, this appendix contains additional information that you need to consider.
Lay of the Land
We discuss the notion of a "class Planet" here, but we do not yet have infrastructure to support classes making their own planets. For those instructors who wish to set up an instance of a Planet feed reader, there are detailed instructions at the Planet Planet site. We hope to provide supporting infrastructure soon.
Getting the Code
For the exercises in this chapter, students will all need access to the version control client.
Best practice, ultimately, will involve giving each student their own account. Since the overhead of that is high, though, we will simply allow students to publish with the following commit info:
- Repo: http://svn.teachingopensource.org/repos/tos/
- Userid: tosguest
- Passwd "I love open source!"
As of this version, this single account is the only account with write access. It's possible that this may change in subsequent versions if someone abuses the repo, but for now, it's the simplest approach. The goal of this repo is just to give everyone a scratch space to play with. None of the code in this repository is important.
Building the Code
By this point, it's absolutely essential to have chosen a project.
The Freeciv examples are just that: examples. The only way to learn how to build a project from source is to build it from source.
If you are an individual learner, you should choose a project that interests you. If you are an instructor, you can either allow the students to pursue their own individual projects, or you can select a single project for the class. Both approaches have their strengths and weaknesses -- but it's essential to have chosen a project by this point.
One good source for inspiration is the Open Hatch Project. They do a good job of aggregating open source projects that have tasks suitable for beginners.
Another possible exercise: figure out why a warning is being thrown during compilation. Dig around Google. What can you find? Can you figure out why this error is being thrown? Is it worth fixing this warning? Why or why not? (Note: in the example given in the chapter, googling the error itself pretty much tells you *exactly* why the error is happening, and why it's probably not worth fixing.)
A note for potential collaborators: in the Java world, Ant and Maven are as ubiquitous as are the Autotools in C/C++ projects. A completely parallel chapter could be written using a project based on Ant or Maven instead of Autotools.
Debugging the Code
Simon Tatham's How to Report Bugs Effectively is a truly outstanding work, and had we not identified it so late in the process, we may well have swiped the text for this chapter. It's licensed under the OPL; in subsequent versions, if we are able to work out licensing issues, we may choose to incorporate this text.
Explaining the Code
This chapter relies upon a wiki installation. Since we are teaching true FOSS participation, it's important that we don't think of the work as throwaway. In particular, the work done for documentation includes taking notes for the class, and those have value of team documentation throughout the class and beuond. For example, future classes can learn from and build on the wiki work done by previous classes, while still conducting a useful exercise. Templates can be borrowed, naming conventions borrowed, while writing new content.
- Wiki needed, recommendation: MediaWiki is well suited.
- You may want to run this chapter early on so the class is self-documenting from the beginning.
- Some of the exercises are best done as part of other exercises, such as documenting obtaining and testing and version controlling code.
Teach two important sections ASAP
Two of the sections in this chapter are useful for early in the class, both the information and exercises. The exercises are used throughout the class, so are useful when taught early or first.
- Explaining_the_Code#Introduction is useful for explaining how the FOSS methodology is useful in non-code situations, which is an essential point to understand. The exercise in this section is to do good code commenting and developer documentation for any code developed in this class. This is a useful exercise to begin early in the class.
- Explaining_the_Code#Documenting_technical_and_community_proceedings also shares a useful FOSS developer skill that is non-coding. The exercise is to work as a class to document the class, and so is most useful when it is begun at the earliest opportunity in the class.
Subsequent editions of the book are likely to refactor this content and move it to an earlier place in the textbook.
Notes for the 0.9 Release
Some issues that we should consider for the 0.9 Release:
- Some chapters begin with a very standard "what you should learn in this chapter" section. Other chapters lack this. We really should strive to make that consistent across all chapters.
- There are a number of terms about which we assume previous knowledge. One simple option is to hyperlink to good explanations of these terms externally; but a better solution might be to link to a glossary at the end of the text. We're starting to collect these in our Glossary of Terms.