The APC plans to release the software that was written in the Action Application project as open source. It is expected that this step will provide benefits both to the Open Source Community as well as to the APC. The Open Source Community will have access to the software and will be able to use it. The APC, as the project maintainer, will benefit from input coming from the Open Source Community. The APC will have to deal with this input in several ways in order to improve the software and to re-release enhanced versions to the Open Source Community.

This document outlines the resources that the APC will have to provide to reach these goals. It also gives information about the process and recommends the use of public resources, that is, SourceForge, for it. Further, it makes up some rules which will help to work together with further software development in this project within the APC as well as with the Open Source Community.

2 How Open Source Development Works

2.1 Open Source Development Philosophy

There are people who suggest that in order to do open source development, you only need to make the source code freely available and the rest will be done by the community. This is, of course, untrue, and a big deal of work has to be done to make a project successful. Success in this regard means that people are interested in the project, that they use the software and that some of them possibly contribute back. People won't do any of these things if the project is maintained badly, that is, if input of any kind is not or too late responded on or if software releases are poorly documented or packaged.

Maintaining an open source project requires a strong idea about what long-term goals the project has. People may come up with feature requests and/or patches, and the maintainer/s have to decide which of them should be accepted to put more work into and which have to be politely rejected.

2.2 Needs for the open source development process

2.2.1 Needs

The successful open source development process involves several needs. The needs listed here come out of the mind of the author and may be incomplete; nevertheless they will be most of it. Needs are split up into the categories „Formal Needs“ which are plans to be developed and agreed on before the release (and for which there are proposals within this document), and „Role Needs“.

2.2.2 Formal Needs (to be developed before release)

2.2.3 Role Needs

3 Formal Needs Descriptions and Suggestions

3.1 Rules for code hacking, documentation, packaging

3.1.1 What this means

The Rules for code hacking, documentation, packaging should help the development team and all the people „out there“ to understand what everybody else does. Writing the source code, documenting it and packaging the releases should happen in a proper and common way. By following such rules, the software package is much easier maintainable and understandable.

3.1.2 Proposal

3.2 A way to set up goals / to get specifications for further development of the project.

3.2.1 What this means

Providing goals for future development is sort of an obvious need. Failure to do so leads to possibly interesting, but somewhat random project results.

3.2.2 Proposal

This is an administrative point which is probably best covered by the APC decision making process on a certain level. It is beyond the scope of this document to make suggestions for this. However, future development directions should be made clear by the APC.

3.3 Feedback

3.3.1 Expected Nature of Feedback

After the release of the AA to the open source community, feedback from the Open Source Community will begin. Feedback can be expected to start slowly and then to rise smoothly as the word of the project reaches more and more people and the project gets on more and more link lists. If, on the other hand, the announcement gets onto a main news site such as slashdot, feedback may suddenly overrun us ("slashdot effect", geeks speak of the project being "slashdotted").

In order to encourage people to use the software and possibly participate in development, there is a need for timely and qualified responses on all requests. If we do a good job here, people will get the impression that the software is actually in use and is maintained well.

All requests should be responded on within 24 hours on week days. Of course this does not mean that all requests are closed by then, but it is best to send an answer confirming that the request was heard and is cared about.

All requests which cannot be immediately closed should be assigned to one person and be given a priority. The person in charge should then care about it as soon as possible. (SourceForge's support, bug tracking and patch manager services provide a very good basis for doing all this.)

We split up feedback into different types: support requests, bug reports, feature requests and other.

3.3.2 Support Requests

3.3.2.1 What it means

Most of the feedback will be support requests from people who try to install and run the software on their systems. We will have to deal with a broad variety of support requests. Requests vary concerning the requester's skills, the operating system / distribution used, the amount of documentation that had been read by the requester, the completeness of the request and the amount of untrue claims the requester makes. In many cases, a response of a support request will only contain a request for further information (version numbers, error messages and so on).

3.3.2.2 Proposal to deal with support requests

Support requests should only be accepted through the support request tracking system. If they get in through other channels, they should be either rejected or forwarded to the support system. Since support requests are something we have work with but normally don't have many benefits from, we softly enforce people to request support in a way that makes us as little work as possible.

New support requests should be dealt with at least once each day. This means that a person responsible for the support requests of the day reads the new requests and either directly answers and closes them or assigns them to the best person to deal with the issue. The request also should get a priority. This person should also look for support requests that are older than a week and still open and investigate about the issue.

Support requests should be answered and closed as soon as possible. If a support request turns out to be something else, for example, a bug report or a feature request, it should be entered into the right place (i.e., the bug tracking system or the feature request forum). Support requests that stay longer than a week unanswered in the queue should be rare, and if so, there should be a good reason why they are still there, and the reason should be mentioned in an intermediate answer on the request. If an issue is too complex to be answered within a normal support task ("... There is no such requirement listed in the preconditions list! How am I to know I need electricity?"), the request should be rejected politely, giving information sources if possible.

If a support request contains a question that uses to come in often (for example, for the third time), the question and its answer should be posted in the FAQ list. The person who answers the support item should then send the question and the answer to the project maintainers who then add it there.

3.3.3 Bug Reports

3.3.3.1 What it means

Bug reports normally make up a smaller part of the feedback that comes in (this may be different if there is a development version out there). Some bug reports are indeed support requests because people think something doesn't work but the software is not to blame. Other bug reports are indeed feature requests. Bug reports come with or without complete descriptions, version numbers, steps to reproduce and so on. They come with or without bug correction suggestions and/or patches.

3.3.3.2 Proposal to deal with Bug Reports

Bug reports should be entered into the bug tracking system if they come in through other channels. Since bug reports are something we need as much as possible, we want to be nicer than concerning support requests.

As with support requests, bug reports should be dealt with at least once a day. This means that a person responsible for the bug reports of the day reads them and assigns them to the developer who is the best to check the report and respond. The bug should be given a priority based on the impact the bug probably has.

Bug reports must of course be checked for correctness. With many bug reports, there will be a need to respond with a list of questions. The goal is to find out if there is indeed a bug and then, which the bogus piece of source code is or if this is a conceptional bug. If the bug reporter suggested a solution already, the developer needs to decide if this solution is the best or if a fix at another place would be more consistent. (For how to try out patches, see “Try out a submitted Patch”). If the bug is conceptional and a fast fix is not possible, the bug should be left open and an entry on the task list should be made.

Bugs should be investigated and dealt with as soon as possible. If the bug has a high impact on software functionality, and if the bug report came with suggestions to fix it, the maintainer should consider to publish the fix, possibly using the patch managing system.

3.3.4 Feature Requests

3.3.4.1 What it means

As people begin to use the software, they will start to have ideas about which features are missing for their way to use it. Also, the developer team will have such ideas, and, hopefully, APC's users will come up with feature requests.

Feature requests may come with more or less detailed descriptions, and there may be requests which could be fulfilled within a few minutes of coding while others would take a lot longer.

3.3.4.2 Proposal how to deal with Feature Requests

Feature requests are to be handled different from both bug reports and support requests, because there is no need for an immediate action. They should be dealt with regularly, but there is no need for a day to day response. A public discussion forum can be used for them so people can contribute to other people's requests, too.

Feature requests should, as a first step, be reviewed by a feature request reviewer. She or he should first check if this is indeed a feature request or if it is rather something else, that is, a bug report or a support request and if so, put it into the appropriate place and inform the requester. Then, she or he should make a first assumption about how important this particular feature request is and prioritize it. The priority should be chosen with regard of the project's goals and the number of people who already requested the same - especially APC people. Also, a first estimate of the resources needed to implement the new feature should be made.

Depending on the „size“ of a feature request, different people are to decide if a specific feature will be implemented by APC contractors or not. Feature requests that will not be implemented by the APC instantly, but have a high priority because they meet the project's goals well, should be posted into a task list („developers needed“), so idle developers from the open source community can contribute to the project in a structured way.

Feature requests can also come in in the form of patches - the feature is requested and at the same time already implemented. Patches should be evaluated by a developer who knows best about this part of the software. They should not be applied to the main development version without check of course. There is often a better and cleaner way to do things which external developers are sometimes doing as a quick hack. Care should be taken not to "pollute" the software with quick hacks coming from the outside.

3.3.5 Other input

There will be other input which is not a support or feature request nor a bug report. This must be handled individually of course.

3.4 Creating new stable versions which can actually be used in production (get usable results)

3.4.1 What it means

In order to get stable and thus well usable software with as little bugs as possible, a releasing procedure needs to be established. This involves releasing different types of packages, the „code freeze“ and testing.

3.4.2 Proposal

3.4.2.1 Dividing versions into a „stable“ and a „development“ branch

Users which have no interest in developing or testing of the package need to rely on stable versions. On the other hand, it is essential for developers or for „power users“ who immediately want the newest features to have current versions of the software. This leads into releasing two different software versions: A stable, and a development (beta) version.

The current stable package must be without known major bugs. If a new bug is discovered in it, it should be fixed soon and if the bug is serious, a new release of the stable package should be made immediately. No changes except bug fixes should be made in the stable version.

The development package should represent the current state of the project. It is not expected to run in production and will have known bugs. New features get into this version, and they may be partly implemented at any time. The development package should be released often and on a regular basis, for example, every 14 days (of course this makes only sense as long as development indeed happens).

3.4.2.2 Code Freeze

At some point in time, the development package must become the stable package so end users can actually rely on and use it. This should happen whenever a set of new features has been implemented which make up a significant step. It is upon all workers on the project to discuss the right moment for this, but it must not be delayed too much - better leave out a feature that does not get ready then wait forever.

The development release is frozen then. This means that no new features are implemented, but all developers instead start testing and fix bugs.

3.4.2.3 Testing

Freshly written code always has bugs. In order for the development package to become the stable package, it must be tested. The project maintainer/s should make sure that everything is tests that needs testing. Normally, every new feature must be tests especially, but there are situations when nearly all the package needs to be tested, for example, when there has been a major rewrite of some core component.

Testing of a specific functionality should not be done by the developer of this functionality, but by someone else. It may make sense to even invite non team members for testing, for example, support staff. Bugs which are discovered while testing must be entered into the bug tracking system (this only takes a minute) - even if they are fixed immediately, so other team members can see it and know it is fixed.

It is up to the maintainer/s to declare the development package to be „tested“ and „stable“ and thus replace the old stable package with a new release from the development side.

3.5 A way to coordinate the hacking of the same source code for several people (concurrent version control system).

3.5.1 What it means

Whenever several people do software development in a team, they need a way to integrate their individual own changes to the code with changes from other people. Also, it is essential to have an archive of old software version and a history of changes. These resources should be public.

3.5.2 Proposal

This is simple, and it is only here for completeness - CVS is the software package that covers this task. It is already used by the AA development team.

Unfortunately, CVS can be complicated to use and requires some basic rules on how to use it to work together effectively. See appendix B for a description of such rules.

3.6 A way to communicate with each other within the development team and with the public

3.6.1 What it means

3.6.2 Proposal

For our purposes, newsgroup style forums would be good. There is already the newsgroup / APC conference apc.apc.wg.toolkit. It is recommended that this is used for internal communication which is not meant for the public only, because the public can't access it. For communication about the development process, a public resource would be better, either a mailing list with archive or a web based „discussion forum“. Mailing lists have the advantage that they can be used off-line.

3.7 Promoting and Announcing

3.7.1 ...to the open source community

In order to actually release the project to the open source community, APC needs to broadcast the information what it is and that it is there (and where). If APC posts this information to some well known places where people search for software, people will find it. Probably the most important place for this is an announcement at freshmeat (http://freshmeat.net/).

3.7.2 ...to the APC

Since APC developed the software thinking it is something useful for APC members, APC should promote the AA to its own members. To do this, a simple announcement will probably not be enough because of the laziness of matter. Members should continuously be informed about the project. Reporting back at meetings, both about how the AA are used as well as how the open source development process works, seems to be fairly important.

3.8 A way to publish information about the project (Web Site)

3.8.1 What it means

Each Open Source Project has a project Web Site. The Web Site usually contains at least

3.8.2 Proposal

If we use SourceForge, we need to put a link to SourceForge on the web site (see below for details).

4 Role Needs Descriptions

4.1 Maintainer/s

4.1.1 Role description

Project maintainers are the ones who make daily decisions. They are responsible for coordinate the development process, to release new versions, to grant or revoke access to project resources, and to enforce the rules everybody agreed on. Maintainers should have the overall overview and know what everybody is currently doing. They should have an idea of time frames and release dates, and it is up to them to decide which code gets included into the package and which is not for some reason.

4.1.2 Proposal

There should be more than one, but not too many maintainers. Two or three seems to be a good number. APC's maintainers of course have to report to APC and will do what APC requests.

4.2 Developers

4.2.1 Role description

The core developer team consists of all people who contribute to the package significantly. They are programmers, UI designers and possibly others.

4.2.2 Proposal

Members of the team will be all those who are APC contractors for the AA development. If people from the Open Source Community start to contribute, they may be invited into the core team. All team members must agree on the rules the development process has before they can get into the team.

5 Using public Open Source Infrastructure: SourceForge

5.1 What SourceForge (http://sourceforge.net/) provides

SourceForge offers several different services to the open source community. Most of them can be switched on and off by the project administrator and it is up to her or him to use or not to use each of them. SourceForge's services include:

5.2 SourceForge terms and conditions

We should be aware of the following issues which come from the usage conditions of SourceForge (these are the important points):

<A
HREF="https://sourceforge.net/projects/PROJECT/"><img
src="http://sourceforge.net/sflogo.php?group_id=GROUPID&type=1"
border=0 height=31 width=88></A>

PROJECT should be replaced by the project's “unix name” and GROUPID by the SourceForge group id. (The height and width numbers are critical so the page loads well even if SourceForge is down.)

5.3 Using SourceForge

SourceForge knows anonymous and logged in users. In order to participate at projects, post messages into discussion forums and so on, users must be logged in. Creating a SourceForge personal account is simple; there is no privacy statement, but email addresses are kept confident and no info about users is visible to other users, except when explicitly switched on.

Projects on SourceForge know three types of participants: (a) Users which just download files or gather information from the web site. These users may be anonymous, unlike all others. (b) Users who are developers for a project, and (c) users who administrate a project.

It is recommended that APC names two or three administrators for the SourceForge project. Project administrators can grant or revoke developer status to/from other users.

5.4 Creating a SourceForge project

The creation of the SourceForge project should be well prepared. In order to set up the project, we

After going through the initial registration process, the project will be set up by SourceForge within a few days.

The creator of the project will be informed about this by email. After the project has been set up at SourceForge, the administrator should open a support request for SourceForge itself, asking to add the other administrators to the list of project administrators (this can't be done automatically).

The creator should also classify the new project in what SourceForge call the "trove map"; this is a software categorization system used to index project within SourceForge.

5.5 Services to use at SourceForge

APC may decide to use only a certain part of SourceForge services. Given the point that the SourceForge service may be terminated any time - which is not very likely but possible, for example, if their sponsor, VA Linux, decides not to pay for it any longer -, it seems a good idea not to put everything onto SourceForge. Services we can provide easily on our own, which already exist and/or which are not too integrated with other services at SourceForge need not to be used there.

On the other hand, the permission system of SourceForge integrates nearly all services (only the mailing lists are not integrated). We probably don't want to duplicate the permission system.

It is recommended that we run the project's web site somewhere else or at least set up a domain name system trick so that the pages are hosted at SourceForge while we have control on the link domain. The SourceForge project overview page would still be in use to access the different SourceForge services.

Using the support system and the patch manager at SourceForge seems to make sense.

The discussion forums and the mailing lists do a similar job, thus using only one of them would be a good idea. Mailing lists tend to be more flexible because you can use them off-line, too.

The cvs repository there has the advantage that anonymous access is already set up, and existing cvs repositories can be imported, so this should probably be used, too.

The bug tracking system seems quite advanced and should be used, too, since it is not clear if the existing IGC bug tracking system will be around forever.

The anonymous FTP space could be used, too, but could be anywhere else as well. Since people will search for links for download on the project web site, we can put a new link there anytime (if, for example, SourceForge fails for some reason).

As of writing this document (June 2000), SourceForge has unfortunately become a bit unreliable (this is the author's personal impression); the server tends to be unreachable once in a while. Hopefully this is not getting worse - we should carefully watch this and keep in mind not to keep the only copy of any critical information there. Especially the CVS repository, if hosted there, should be backed up once a day.

6 Making AA Open Source Release Ready

6.1 Making the Source Code Release Ready

There are some preconditions for a software project to be released as Open Source or, to be more exact, to be released at all. Releasing as Open Source means to donate to the community, but if we expect to get something back, we should take care that the project is properly packaged, documented, and accessible so people will relatively easily get it to run and will have the possibility to make changes and to contribute back.

These tasks are of course something ongoing. All this needs to be done continuously.

6.2 Documentation

Whether or not a software project is open source, it needs to be properly documented. Different documentation sets for different target groups need to be prepared:

In the AA case, the end user documentation consists of two parts: (a) the documentation for sites who want to provide the AA services to their users, and (b) the documentation for those users. The creation of all of these are part of what APC does anyway; the documents need to be included into the open source release.

The documentation should be detailed and complete at some point in time which is not necessarily before the first release.

The source code should be initially reworked in order to match the rules the development team agreed upon starting the open source development process as outlined in section 3.1, „Rules for code hacking, documentation, packaging“.

7 Resources

7.1 Expected amount of feedback

It is very hard to estimate the weekly work that has to be done maintaining the package. There will be support requests, feature requests, bug reports and complaints. Maybe some people also start to hack it and send in patches.

It is recommended to allocate two hours of one person each day for the immediate responses on this feedback for the beginning. In-depth evaluation of feedback is covered by another two hours daily. After eight weeks or so, the actual time used for this should be reevaluated. This includes dealing with the feedback only; there is no development of new features included.

7.2 Resources that need to be allocated

Resulting from the needs outlined in the previous chapters, the following tasks are to be taken over for the process. All numbers in the „time needed“ column are estimates. If there is more than one person suggested in the “who” column, the “time needed” is the time for all of them together.

Task	Section Number	when	who	Time needed
Develop / decide about / agree on rules and procedures for coding, packaging, dealing with feedback, releasing etc. (suggestions are in this document)	3	once before release	APC, development team
Set up goals and get specifications for future development; decisions about development of proposed features	3.2	ongoing	APC
Daily feedback management (deal with support requests, bug reports, feature requests and other input)	3.3	daily	developer	2 h /day = ¼ worker
In-depth dealing with feedback (support, bug investigating etc. as assigned to specific developers from daily feedback management)	3.3	when needed	developer	2 h / day = ¼ worker
Maintaining the software: Supervise development process; keep overview; release packages; insist on following rules; code freeze / test management; CVS repository, SourceForge project and Web Site management	4.1	ongoing	maintainers (2 or 3)	½ worker
Test	3.4.2.3	on code freeze	developers, APC support staff	calculation is part of specific development step plan
Actual feature development	4.2	on feature implementing decision	developer	calculation is part of specific development step plan
Create documentation for end user (end user is the one who uses AA on their web site - not their user!) where it is missing („big picture install docs“)	6.2	before release	APC contractor (Moritz)	5-8 work days
Create documentation for developer / document functions, data structures etc. where it is missing; rework source code to meet the rules the team agrees on	6.2	before release	current developers	2 work days (?)
Promoting and Accounting the release, reporting to the APC and the public about progress	3.7	on release and ongoing	maintainer/s	1 day on initial release

8 Appendix A: Rules for Hacking

8.1 Coding

If the program behaves in a better way, it is of course the right thing to update the documentation. The idea with this rule is to put an emphasis on the documentation and to strengthen the idea of updating it before the new feature is implemented.

8.2 Packaging

Following common standards, this means to put the primary package into a .tar.gz file. The file should be named using the form

where MAJOR, MINOR and RELEASE are version numbers. The tar archive contains one directory at top level with the name

which contains everything else. The file should not contain CVS directories (to create it, use "

cvs
export -d

... ").

The license information should be copied to the header of all files as a comment with contact information (this is recommended by the Free Software Foundation).

9 Appendix B: Using CVS

9.1 CVS in General / Know-How

The use of CVS requires a certain amount of knowledge. The following CVS advice and information is intended for those who already have basic knowledge about CVS. A possible source for such knowledge is the “Introduction to CVS” by Jim Blandy (http://www.cvshome.org/CVS/Docs/blandy).

Also, some descriptions here do not go into depth about CVS issues that can better be read elsewhere. The main reference document about CVS is the “CVS manual” which can be found at http://www.cvshome.org/CVS/Docs/manual/.

9.2 The Repository

CVS organizes the repository contents into modules. It is recommended to put the source code for the whole project into one module and keep the same directory structure within the module as it would be in the distribution .tar.gz file.

No manual file operations should be done on the repository except for tasks which can't be done through CVS itself. (For example, renaming a file should be done by removing and adding it again under the new name.)

9.3 CVS etiquette

No files that can be recreated by the build process should be put into the CVS. On the other hand, everything that is needed to build and install the software should be included.

No non-working versions should be committed. A version is considered non-working if it does not compile properly or whose main functions do not function.

Branches and tags should be created in a meaningful and consistent way. If possible only maintainers should do this. A tag should be created on every release of a version so this version can be checked out later using the version number. Thus the tag should be named after the version number (cvs tags need to start with a letter and can't contain dots; a possibility is to prepend the number by a “v” and replace any dots by underscores.)

The current (stable) and development versions of the package should be within the same CVS module and repository. The development version should be the main trunc. In case a stable, released version needs a fix, a branch from that version should be used and the fix should be committed to that branch. This “stable bug fix” branch should be named like the tag of that version with “-fix” appended. It should be created whenever the first stable version is released and then whenever a development version becomes the stable version.

The “stable bug fix” branch must be merged into the main development trunc. Depending on the state of development, this may happen sooner or later. Whenever modifications from the “stable bug fix” branch are merged into the development trunk, the “stable bug fix” branch should be tagged with something like “merged_into_main_trunk” so that new fixes to the “stable bug fix” branch can be merged without merging the already-merged old fixes again. There is a longer explanation of this concept in the CVS manual under “Branching and merging”. It also has an example.

10 Appendix C: Step by Step Instructions for Developers

10.1 Preparations

You will need ssh (secure shell) version 1 installed on your system. And obviously, you will need cvs. If you don't have them, find, build and install them. (A starting point to find them is freshmeat.net).

In order to tell cvs that you want to make connections through ssh, you will need to set an environment variable:

Also, in order to use compression by default, you might want to create a file named “~/cvsrc” and put this into it:

In order to use the cvs, you will need a user account at the cvs server. In the case of SourceForge, this is your normal SourceForge account name and password.

While writing this document, the SourceForge cvs repository would sometimes not be reachable. The following message was printed on my terminal:

(The message may also mean that you haven't set the CVS_RSH environment variable properly.)

10.2 Simple CVS operations for apc-aa

To start hacking, that is, to check out a working version of the aa module, development version, change to your home (or your preferred source) directory and enter the command

Replace USER by your user id on the cvs server. This will check out the current development version and put it into a new directory named “apc-aa”. You can now start hacking, that is, modify the files in the directory, and/or delete as well as add files.

If you have added a file and want it to become a permanent member of the module, change into the directory where the file lives and issue

Replace file with the file name you are about to add. (If you don't do this, other people won't get the new file.)

If you have removed a file, you must tell cvs that it was deleted by intention, not by accident. To do so, enter

After you have implemented a new feature or fixed a bug (or finished whatever task you were up to), you should commit your changes to the repository so the other developers will receive your changes, too. In order to do so, change to the top-level module directory apc-aa and fire off the command

CVS will then gently force you to add a comment about what you have done to the source code. Take your time and enter it - be complete and verbose so other developers are able to see what you did and why.

If the commit aborts with the message “Up-to-date check failed!”, someone committed her or his changes to the repository since you did your checkout. In that case, you need to “update” your working version to the state of the repository before you can commit your changes. To do so, change to the top-level “apc-aa” directory and use the command

Your working directory will be updated the the current development version. Don't be afraid about your changes - the current version from the repository will be merged with your changes. If cvs can't merge a part of a file, it will report a conflict or another problem. Carefully examine the cvs output on updates. In case of conflicts, you need to resolve them before you commit (don't ever commit files which still contain conflicts!).

The update command can also be used to “freshen” a working directory if you haven't changed an files. In practice, most cvs users do a checkout only once at the start of a project, and then only do “updates” and “commits”.

10.3 Try out a submitted Patch

Suppose you need to try out a patch that came in through one of the feedback channels (probably as a bug report or as a feature request). You want to try out the patch and see what it does.

Put the patch into a file somehow. Be careful not to mess with white space and tab characters (they should stay as they are). Never mind about additional garbage in that file such as mail headers, patch will ignore that.

Before applying the patch, take a quick look at it. First, see if the patch really is doing what you expect. Many patches contain too much then they should - the creator of the patch might have make changes to files which are unrelated to the thing the patch is supposed to do. Politely reject such patches and ask the creator to send a new one, only containing the relevant stuff.

There are two basic possibilities how the patch was created: From within the package or from the outside. Look for the file names in the patch file. If the directory “apc-aa” is included in the file names, it was made from outside. If the file names consist of the file names themselves or start with directory names which are within the package, it was made from “within”. Remind that.

It is good to know which version of the package this patch has been made against since the result can be different if you apply the patch to different versions. However, most patches still work even if the source code had been modified so it is somewhat different from the original version. Also you don't want to modify an old version but rather merge the patch into the current development or the current stable version of the module.

Depending on whether you are about to try the patch on the stable or on the development version, tell cvs to give you that version. If you want to have the current development version, use the command

If it is a fix to the current stable version, you need to know which the current stable version is because you need the correct stable bug fix branch name. The name should is a “v”, followed by the version number with dots replaced by underscores, followed by “-fix”. Thus, if the version you are fixing is 2.34, it would be “v2_34-fix”. In that case, use this command:

If the cvs tells you “cvs [server aborted]: no such tag v2_34-fix”, blame the maintainers and tell them to read section “CVS etiquette”.

Go and change to the newly checked out package version directory apc-aa-try. Then apply the patch by issuing

If the patch was made from outside, add “-p1” as an option to the patch program.

Patch should now tell you which files it has patched. Go and test the patch. If you want to accept the patch and put it into the repository (make your patched version the current development or current stable version), simply issue

from within the apc-aa-try directory. The change is then committed to the correct version (the stable or development, depending on which one was checked out).

10.4 Releasing a new development or release version

10.4.1 Releasing a new development version

Figure out the new version number and tag the current development version with it. For example, if the version number will be 2.34, go into your working directory which contains the version you want to release, and tag it with

The “-c” flag will make sure that the repository and your working directory are up to date.

You have now “frozen” the version you will release. You can now export this version and make a distribution archive from it. To do that, go into a directory outside of the working directory, for example, your home, and type

The first command will export the tagged version into a new directory “apc-aa-2.34” (the “export” instead of “checkout” makes sure no CVS directories are created). The tar command will create the .tar.gz archive in just the way we want it.

Upload the new release to SourceForge (use “File Release”) and to any other places we want people to download it from.

10.4.2 Releasing a new stable version from the development version

In case you are about to release a new stable version after the development version has been successfully tested and fixed, in other words, if the development version should become the stable one and a new development version is to be started, do exactly the same as above (“Releasing a new development version”). You probably just use different version numbers (incrementing the minor number at least).

After having put the new release into the right places for download, you probably want to write up an announcement and publish it on the project web site and so on, but before you do that, make future bug fixes on the new stable version possible by creating a branch tag which becomes the “bug fix stable” branch. Assuming your new released version was 2.1, go back into your working directory and enter

10.4.3 Releasing a “bug fix” version without changes from the current development version

If a bug in the stable version has been discovered and fixed, you will want to release a new “bug fix” stable version. In that case, you need a checked out working version of the current “stable bug fix” branch. To create it, go to your home directory and type

This example assumes you want to fix the stable version 2.1. cvs creates the directory apc-aa-2.1 and puts version 2.1 in it. The hack away, fixing the bug. After you have tested your fix and are ready to release, figure out a new version number - let's say, 2.11. Then do the following from the working directory apc-aa-2.1 (see the previous sections for more verbose comments on these commands):

Consider merging the fix into the development version, too. See next section about that.

10.5 Handling an urgent bug-fix to both the development and stable release versions

Now you want to merge the fixes done in the stable version into the development version. cvs helps you a lot doing this, but still you need to be aware of a few things.

Although cvs always knows which version you checked out into your working directory, it does not keep track of which changes from another branch you have already merged into some branch. Put differently, it does not know how much of the fixes in the stable branch have already been merged into the development trunk. Thus, we need to keep track of this by ourselves.

Whenever fixes from the current stable version are merged into the development trunk, the stable version which has been merged should be tagged with “merged_into_main_trunk”. If the last release of a stable version followed the rules this paper suggests, the tag should be there. Now go into your checked-out development version working directory and make sure it is up to date:

Then, merge the changes that have been made to the stable bug fix branch between the last merge and now into your working directory. Assuming the stable version that was just released and which contains the new fixes is 2.11, enter:

As with every update, cvs might report errors and conflicts which should be examined carefully. If the fix is fairly unrelated to the current development, chances are high that no conflict is created. (However you might want to check if the fix was applied correctly.)

You now have to move the tag “merged_into_main_trunk” so future merges will have a point of reference! To do so, use the command