From Teaching Open Source
[edit] DEPRECATED OUTLINE
This outline is deprecated. Please consult the chapter outline at FLOSS Manuals for the current work.
PRACTICAL FREE AND OPEN SOURCE SOFTWARE ENGINEERING
[edit] Introduction to FOSS
This chapter gives an overview of the FOSS world.
[edit] What is Free and Open Source Software?
[edit] What is source code?
[edit] When we started to hide the source, and why.
[edit] Why is FOSS so popular now?
[edit] Who would buy a car with the engine welded shut?
[edit] When FOSS is better: Apache versus IIS
[edit] Who Cares about FOSS?
[edit] A bunch of companies, and what they do with FOSS, and why
[edit] The Third Sector
[edit] Your future boss can see you coming!
[edit] Licensing 101: why it matters
[edit] Licenses provide rights to developers
[edit] BSD style licenses, good and bad points
[edit] GPL style licenses, good and bad points
[edit] Case study: why did project $FOO choose GPL/BSD?
[edit] Supplement: Read The Cathedral and the Bazaar.
[edit] Supplement: Watch Revolution OS
[edit] Exercise: Which license would you choose?
[edit] Getting started in a FOSS project
This chapter deals with how to research a FOSS project, so that you know enough to start contributing.
[edit] Selecting a project
[edit] Interest: What kinds of projects interest you?
[edit] Maturity: Is a project ready for your help?
[edit] Skills: What do you have, and what do they need?
[edit] Mentors: Who will bring you into the club?
[edit] Commercial Ties: Why do they matter? Instant interview?
[edit] = Case study: why Will Cohen's student chose project $FOO
[edit] Supplement: Project List
We should be able to provide, as reference, a list of the projects who are working with TOS and have a strong onboarding program for students. This reference can live online and be continually evolving.
[edit] On Being a Beginner
[edit] I don't know what I'm doing, how can I possibly help?
[edit] Coping versus knowing.
[edit] The courage to begin.
[edit] Case studies: how did you get started in community $FOO?
[edit] Exercise: Reaching Out
The student should reach out to a few projects, select a project to work on based on the responses, and be able to defend that choice.
[edit] Source code management
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.
[edit] An overview of source code management tools
[edit] Why source code management matters: order versus chaos
[edit] Centralised revision control tools: cvs, subversion
[edit] Distributed revision control tools: git, mercurial, bazaar
[edit] Case study: why did large project $FOO change RCS?
[edit] Exercise: Downloading from a repo
[edit] Building the code
[edit] What is "building"?
[edit] Makefiles and what they do
[edit] GNU automake/autoconf and why they are useful
[edit] Java build tools: Ant, Maven and friends
[edit] 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.
[edit] Patching the code
[edit] What is a "patch"?
[edit] 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.
[edit] How to create a simple patch
Put it all together. How to change something locally and wrap it up into a patch.
[edit] 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.
[edit] Exercise: Creating a Patch
The student should create a simple patch and demonstrate that it applies properly against his or her chosen project.
[edit] Committer access
[edit] What is a "committer"?
[edit] When do you become a committer?
[edit] What are the responsibilities of the committer?
[edit] How to apply a patch to code and commit that patch
[edit] Exercise: Applying a Patch
[edit] Bugs: Finding them, killing them
This chapter covers various bug tracking tools, how to write a good bug, how to verify a bug, and how to get the most out of bug reports.
[edit] Bug trackers
[edit] Why a bug tracker matters
[edit] Overview: trac
[edit] Overview: bugzilla
[edit] The anatomy of a good bug
[edit] A good bug is still present in the latest build.
[edit] A good bug has enough information, but not too much.
[edit] Exercise: Is this a good bug?
Read a set of bug reports. What is good/bad? How would you modify them to improve them?
[edit] A good bug has a reporter who will help the developer get it fixed.
[edit] A good bug is any bug that the developer can replicate!
[edit] Case study: GNOME bugmasters
Really, we need to find as many good examples as we can of best practices inside the open source world, since there are so few of them. We may also want to cop to the notion that bugfixing in open source projects often isn't very good, but make the point that proprietary products are often much worse -- you just don't know it.
[edit] Exercise: Replicating Bugs
Pick three NEW bugs in your chosen project, and try to replicate them in your latest version. If you succeed, note it in the bug. If you cannot replicate, note that too. Provide as much info as possible.
[edit] Analyzing bugs
Once you can reliably replicate the bug, you've done most of the work needed to fix the bug.
[edit] How to read code
Is this something that can reliably be put into a chapter? FIXME. There's always the obvious stuff, like grepping the code for text of errors generated, putting in logic checkpoints to narrow the scope of the problem, and so forth. Do some research on good materials here.
[edit] Exercise: Finding the bug
Select a bug that has been previously identified as replicable, dig into the codepath, find the lines of code that cause the error, and update the bug with a statement of where, exactly, the bug is.
[edit] Exercise: Fixing the bug
This can be the hardest part, but give it a shot. In the bug that was just found, fix it to see if it solves the problem on your local machine, and then submit that fix as a patch to the developers, either as an attachment to the bug or as an email to the developer mailing list.
[edit] Case study: Great Bug Finds by talented amateurs
[edit] Documentation
FIXME.
[edit] Testing
FIXME.
[edit] Adding new features
[edit] Where do new features come from?
Sometimes, a developer just writes them, because they are users too, and they can write their own features. Often, though, users request them; they may not know how to write them, but they do know what they want. At least, sometimes they do. Sometimes they don't. It's the job of the developer to figure out what the user wants, and how to deliver it -- or whether it even makes sense to deliver it.
[edit] What makes a good feature?
Good question. Some basic stuff here. Talk about the different approaches to features? Huge complex specifications are for airplanes. Concentrate on the agile approach to feature specification and development? Do some research. Talk about diagrams, use cases, UML, HCI. And then FIXME. How much do we overlap into SW engineering here? This could be a whole text.
[edit] Exercise: Good Feature, Bad Feature
Look through your project's repository of feature requests. Find one feature that you think is bad, and find one feature request that you think is good. Compare and contrast.
[edit] Exercise: Proposing a feature idea
Submit feature requests to user-community to get feedback on their idea from a feasibility perspective.
[edit] Exercise: Turning a feature request into a feature specification
Find a poorly or ambiguously worded feature request. Research its history, what the user is trying to do, if other users are trying to do this, and then put together a feature specification that future developers could plausibly use to build an actual feature.
[edit] Case study: How project $FOO manages new feature development
[edit] Exercise: Writing a new feature, at last
Write the code. You've been working up to this. Give it a shot. Be brave. If it doesn't work, it gives the next person a place to start from. If you've done the upfront work, if the spec is good, the use of the feature well-understood, and if you've got some pseudocode, it's time to get to work, and keep working until it's done and ready to be submitted as a patch.
[edit] Case Study: Samba
This chapter looks at the Samba project in some detail, as a case study of a FOSS project.
[edit] Release Early, Release Often
Now that you own code in a project, how should you treat that code? The philosophical conclusion to the book, really. You may even be a committer by now. How do you behave?
[edit] Other content
This is content that I haven't quite figured out how to fit into the flow of the textbook.
[edit] FOSS History
This chapter gives an overview of the history of FOSS, covering some key developments that have led to the FOSS world of today.
[edit] Inside FOSS Licensing
This chapter looks at the main FOSS licenses and how they impact on FOSS development.
[edit] FOSS and the law
This chapter looks at how FOSS interacts with the legal system.
[edit] FOSS Governance
This chapter looks at how FOSS projects are governed. Includes the different types of foundations and community cooperatives.
[edit] FOSS and Business
This chapter looks at how the business world interacts with FOSS projects. Includes worker and consumer cooperatives.
[edit] What motivates a FOSS developer?
This chapter looks at the diverse motivations of FOSS developers.
[edit] FOSS Distributions and Platforms
This chapter looks at the wide range of FOSS distributions and platforms that they run on.
[edit] FOSS Culture
This chapter delves into the world of FOSS culture.
[edit] Starting a new project
This chapter looks at what is involved in staring a new FOSS project.
[edit] FOSS Tales
This chapter examines some key events of the past few years that have shaped the FOSS world.
[edit] Miscellaneous
[edit] Questions
- How do we deal with multiple platforms? Should we assume a Linux development environment or not?
[edit] Comments
- Each chapter should consist of content and exercises.
- Each exercise, as far as possible, should contribute directly to the well-being of an open source project.
- Should we provide an instructor's workbook as well?