Appendix: Collaboration

Diomidis Spinellis
Department of Management Science and Technology
Athens University of Economics and Business
Athens, Greece
dds@aueb.gr

Mailing Lists

Easy to setup through /etc/aliases
Create pointers to owners and files
Create pointers to files
mobinet: :include: /home/kfouskas/mobinet
mobinet-request: kfouskas@aueb.gr
owner-mobinet: kfouskas@aueb.gr
The file contains the list's addresses
For high-churn lists consider Mailman (http://www.gnu.org/software/mailman/) or Majordomo (http://www.greatcircle.com/majordomo/).

VCS Notifications (CVS)

Arrange for your VCS to notify all committers
Committers can arrange for a special folder for these notifications
Concept similar to ATC radio channel

Example Notification

Date: Sat, 19 Aug 2006 08:24:01 +0000 (UTC)
Subject: cvs commit: src/usr.bin/pkill Makefile
X-FreeBSD-CVS-Branch: HEAD

yar         2006-08-19 08:24:01 UTC

  FreeBSD src repository

  Modified files:
    usr.bin/pkill        Makefile
  Log:
  Install pkill(1), aka pgrep(1), to /bin so that rc scripts
  can use this small and nifty utility.  Create compatibility
  symlinks from /usr/bin for the time being to avoid breaking
  custom scripts relying on the hardcoded path to the utility.

  Idea by:        des
  Discussed with: brooks (in cvs-src and cvs-all)

  Revision  Changes    Path
  1.6       +5 -0      src/usr.bin/pkill/Makefile

Setting up CVS Notifications (CVS)

Add a line in CVSROOT/loginfo

^projname /home/dds/bin/cvs-log %s projname projname@domain.org

Create a notification script

Example:

#!/bin/sh
(
        id -P |
        awk -F: '{
                print $1 " (" gensub(",.*", "", "", $8) ")\t" strftime("%F %R:%S %z (%Z)")
        }
        END {
                print "\nRepository: '"$2"'\n"
        }'
        echo "Directory: $1"
        egrep -v '^In directory|^Update of'
) | mail -s "[$2] cvs commit $1" $3

Setting up CVS Notifications (git)

State project name for Git by altering first row of $GIT_DIR/description

Inform Git about the mail configuration by appending in $GIT_DIR/config

[hooks]
        mailinglist = email1@example.com email2@example.com
        senderemail = myemail@example.com

Create a notification script in $GIT_DIR/hooks/post-commit.sample

#!/bin/sh
#
# An example hook script that is called after a successful
# commit is made.
#
# To enable this hook, rename this file to "post-commit".
projectdesc=`sed -ne '1p' "$GIT_DIR/description"`
recipients=`git config hooks.mailinglist`
full_commit_log=`git log -p -1 HEAD`
commit_msg=`(git log -1 HEAD |
egrep -v '^commit|^Author|^Date')`
(
        id -P |
        gawk -F: '{
                print $1 " (" gensub(",.*", "", "", $8) ") committed:"
        }
        END {
                print "\nRepository: '"$2"'\n"
        }'
        echo "Branch of commit is: `git branch`\n"
        echo "$full_commit_log"
) | mail -s "[$projectdesc] git commit '$commit_msg'" $recipients

Rename post-commit.sample to post-commit
```
 mv post-commit.sample post-commit
```
Change permissions of post-commit to be able to execute
```
 chmod a+x post-commit
```

Documentation is Ubiquitous

System specification
Software requirements specification
Design specification
Test specification
User documentation
- Functional description
- Installation instructions
- Introductory guide, tutorial
- Reference manual
- Administrator manual

Wikis

Advantages of Wikis for storing documentation.

Low-overhead editing
Always current
Revision history
Easily accessible

Things to put on a wiki

Project scorecards
Personal pages (assgined projects, tasks, planned vacations)
Time schedule
Setup, build, release documentation
Specifications
Third party documentation pointers

Wiki Best Practices

Assign people roles
Publish charter
Establish naming conventions
Personal pages
Meeting agendas / minutes
Create templates
Use categories
See also wikipatterns.com (http://www.wikipatterns.com/)

Issue Tracking

Together with VCS the two most important process-oriented tools
Holds bugs, problems, ideas
Each issue gets a unique id
Should be coordinated with VCS

Issue Reports

Track bugs according to:

area of functionality
state
resolution
priority
severity

Example: Bugzilla

Severity of a Bug

Blocker	Blocks development or testing work (e.g. a build)
Critical	Crashes, loss of data, severe memory leak
Major	major functionality problem
Minor	Minor functionality problem, or easy to work around
Trivial	Cosmetic problem
Enhancement	Request for enhancement

An Issue's Lifecycle

Resolution Options

Fixed
Invalid (not a bug)
Won't fix
Duplicate (of another bug)
Works for me
Moved (to another project)

Example: Releasing

Before a release.

Triage bugs
- Fix
- Document
- Hide feature
- Next release
Introduce a code freeze period
- Only showstoppers ...
- ... with no workaround

Bug Tracking Best Practices

Use an existing issue tracking system
No more than one bug per issue
Include bug replication information
Associate VCS commits with bug ids
Minimize the number of bugs left open
Use priorities to manage the developer workload
Backup your issue database