Codendi 4.0 User Guide

Codendi User Guide
"Collaborative Software Development and
Project Management for the enterprise"
www.codendi.org

Version 3.6

Copyright © 2000-2008 Xerox Corporation, Codendi.
This document is licensed under the GNU General Public License version 2.

Copyright protection claimed includes all forms and matters of copyrightable material and information now allowed by statutory or ju-
dicial law or hereinafter granted, including without limitation, material generated from the software programs which are displayed on
the screen such as icons, screen displays, looks, etc.

Printed in United States of America

Xerox ®, The Document Company ®, and all Xerox products mentioned in this publication are trademarks of Xerox Corporation.

This document was formatted with the DocBook XML DTD. HTML version rendered with DocBook HTML native renderer. PDF ver-
sion rendered with Apache FOP.

Table of Contents

1.Introduction.......................................................................................................................1
2. Codendi Site Overview ..................................................................................................... 4
2.1. CODENDI HOME PAGE ............................................................................................... 4
2.2. THE CODENDI MAIN MENU ......................................................................................... 4
2.2.1. Software Map (or Project Tree) ..................................................................... 6
2.2.2. The Code Snippet Library ............................................................................. 7
2.2.3.Help...............................................................................................................9
2.2.4. The Search Facility ....................................................................................... 11
2.3. THE CODENDI DASHBOARD ........................................................................................ 11
3. Becoming a Codendi Citizen ........................................................................................... 13
3.1. CLASSES OF CITIZENS ............................................................................................... 13
3.2. USER REGISTRATION ................................................................................................. 13
3.3. LOGIN AND PERSONAL PAGE ...................................................................................... 15
3.4. ACCOUNT MAINTENANCE ............................................................................................ 16
3.5.PREFERENCES ...........................................................................................................16
4. Creating a New Project ..................................................................................................... 18
4.1. PROJECT REGISTRATION ............................................................................................ 18
4.2. POST-REGISTRATION CONFIGURATION ........................................................................ 20
5. Project Summary .............................................................................................................. 21
5.1. ACCESSING A PROJECT SUMMARY PAGE .................................................................... 21
5.2. PROJECT SUMMARY PAGE CONTENT .......................................................................... 22
6. Project Administration ..................................................................................................... 25
6.1. PROJECT ADMINISTRATION MENU ............................................................................... 25
6.2. ADDING/REMOVING USERS ......................................................................................... 25
6.2.1. Add a user ..................................................................................................... 25
6.2.2. Import a list of users ...................................................................................... 25
6.2.3. Removing a user ........................................................................................... 26
6.3. PROJECT PUBLIC INFORMATION .................................................................................. 27
6.4. PROJECT CATEGORIZATION ........................................................................................ 27
6.5. PROJECT TYPE .......................................................................................................... 27
6.6. SERVICE CONFIGURATION .......................................................................................... 28
6.6.1. Creating or Updating a Service ..................................................................... 29
6.6.2. Deleting a Service ......................................................................................... 29
6.7. SERVICES ADMINISTRATION ........................................................................................ 30
6.8. REFERENCE PATTERN CONFIGURATION ...................................................................... 30
6.8.1. Reference Overview ..................................................................................... 30
6.8.2. Predefined Reference Patterns ..................................................................... 31
6.8.3. Reference Usage .......................................................................................... 32
6.8.4. Creating or Updating a Reference Pattern .................................................... 32
6.8.5. Deleting a Reference Pattern ........................................................................ 33
6.9. USER PERMISSIONS ................................................................................................... 33
6.10. USER GROUPS ........................................................................................................ 35
6.10.1. User Groups Management .......................................................................... 35
6.10.2. Creating a User Group ................................................................................ 36
6.10.3. Updating a User Group ............................................................................... 38
6.10.4. Deleting a User Group ................................................................................ 38

6.10.5. Additional Information on User Groups ....................................................... 38
6.11. PROJECT DATA EXPORT .......................................................................................... 38
6.11.1. Exported Data ............................................................................................. 39
6.11.2. Text File Export ........................................................................................... 39
6.11.3. Direct Database Access .............................................................................. 40
6.12. TRACKER ARTIFACT IMPORT ..................................................................................... 41
6.13. PROJECT HISTORY ................................................................................................... 42
6.14. ACCESS LOGS ......................................................................................................... 42
7. Tracker Service ................................................................................................................. 44
7.1. TERMINOLOGY AND COMMON FEATURES ..................................................................... 44
7.2. ENTERING THE TRACKER SERVICE ............................................................................. 44
7.3. NEW ARTIFACT SUBMISSION ....................................................................................... 45
7.4. ARTIFACT BROWSING ................................................................................................. 47
7.4.1. Selection Criteria ........................................................................................... 47
7.4.2. Favorites and Predefined Tracker Queries ................................................... 49
7.4.3. Tracker Search Results ................................................................................ 50
7.5. ARTIFACT UPDATE ..................................................................................................... 52
7.5.1.Header..........................................................................................................52
7.5.2.Comments.....................................................................................................53
7.5.3. CC List .......................................................................................................... 54
7.5.4. Artifact Attachments ...................................................................................... 55
7.5.5. Artifact Dependencies ................................................................................... 56
7.5.6. Artifact Cross-Referencing ............................................................................ 56
7.5.7. Permissions on artifacts ................................................................................ 57
7.5.8. Artifact History ............................................................................................... 57
7.6. ARTIFACT MASS CHANGE ........................................................................................... 58
7.6.1. Selection Criteria ........................................................................................... 58
7.6.2.Update..........................................................................................................59
7.7. ARTIFACT DUPLICATION ............................................................................................. 60
7.8. E-MAIL NOTIFICATION ................................................................................................. 60
7.9. TRACKER ARTIFACT IMPORT ....................................................................................... 61
7.9.1. When to use the Import ................................................................................. 61
7.9.2. Exporting Excel Sheets in CSV Format ........................................................ 61
7.9.3. CSV File Parsing ........................................................................................... 61
7.9.4. The Database Update ................................................................................... 62
7.10. DEFAULT TRACKER ACCESS PERMISSIONS ............................................................... 63
7.11. TRACKER CREATION ................................................................................................ 64
7.12. CODENDI-WIDE TRACKER TEMPLATES ....................................................................... 65
7.12.1. The Bug Tracker Template ......................................................................... 66
7.12.2. The Patch Tracker Template ...................................................................... 66
7.12.3. The Support Request Tracker Template ..................................................... 66
7.12.4. The Task Tracker Template ........................................................................ 67
7.12.5. The Scrum Backlog Template ..................................................................... 67
7.13. TRACKER ADMINISTRATION ....................................................................................... 67
7.13.1. General Configuration Settings ................................................................... 68
7.13.2. Permissions Management .......................................................................... 69
7.13.3. Field Sets Management .............................................................................. 71
7.13.4. Field Usage Management ........................................................................... 73
7.13.5. Field Values Management .......................................................................... 77
7.13.6. Field Dependencies .................................................................................... 80
7.13.7. Canned Responses .................................................................................... 86
7.13.8. Tracker Report Management ...................................................................... 87
7.13.9. Tracker Graphical Report Setting ............................................................... 90

7.13.10. Email Notification Settings ........................................................................ 93
8. File Release ....................................................................................................................... 96
8.1. SOURCE CODE RELEASE: GUIDELINES ....................................................................... 96
8.2. FILE RELEASE JARGON .............................................................................................. 96
8.3. FILE RELEASE BROWSING AND DOWNLOAD ................................................................. 98
8.3.1. Browsing packages ....................................................................................... 98
8.3.2. Browsing releases ......................................................................................... 99
8.3.3. Downloading files .......................................................................................... 99
8.4. FILE RELEASE DELIVERY AND ADMINISTRATION ........................................................... 99
8.4.1. Package Administration ................................................................................ 100
8.4.2. Release Administration ................................................................................. 101
8.5. PROCESSOR LIST ADMINISTRATION ............................................................................ 104
9. Version Control with CVS ................................................................................................ 105
9.1. CVS: CONCURRENT VERSION CONTROL .................................................................... 105
9.1.1. CVS Clients ................................................................................................... 106
9.1.2. CVS References ........................................................................................... 107
9.2. CVS INTEGRATION IN CODENDI .................................................................................. 107
9.2.1. The CVS Repository ..................................................................................... 107
9.2.2. CVS Access Control ..................................................................................... 108
9.3. THE CVS WEB INTERFACE ......................................................................................... 108
9.3.1. Browsing The CVS Repository ..................................................................... 109
9.3.2. Querying CVS ............................................................................................... 109
9.3.3. Cross-Referencing Artifacts and CVS Commits ........................................... 111
9.3.4. CVS Administration ....................................................................................... 112
9.4. A TYPICAL CVS LIFE CYCLE ...................................................................................... 113
9.4.1. Logging In ..................................................................................................... 113
9.4.2. Importing Existing Source Code ................................................................... 114
9.4.3. Checking Code Out ....................................................................................... 115
9.4.4. Updating the Source Code ............................................................................ 115
9.4.5. Committing your Changes ............................................................................ 116
9.4.6. Contributing your Changes (other users) ...................................................... 117
9.4.7. Exporting and Packaging .............................................................................. 118
9.5. CVS FOR PROJECT ADMINISTRATORS ........................................................................ 118
9.5.1. More on CVS Access Control ....................................................................... 118
9.5.2. CVS Administrative Files .............................................................................. 119
10. Version Control with Subversion .................................................................................. 120
10.1. SUBVERSION: THE NEXT GENERATION CVS ............................................................. 120
10.1.1. Subversion Clients ...................................................................................... 121
10.1.2. Subversion References ............................................................................... 122
10.2. SUBVERSION INTEGRATION IN CODENDI .................................................................... 123
10.2.1. The Subversion Repository ......................................................................... 123
10.2.2. The Subversion Repository Structure ......................................................... 123
10.3. THE SUBVERSION BROWSING INTERFACE ................................................................. 124
10.3.1. Browsing The Subversion Repository ......................................................... 124
10.3.2. Querying Subversion .................................................................................. 125
10.3.3. Cross-Referencing Artifacts and Subversion Commits ............................... 126
10.4. SUBVERSION ADMINISTRATION INTERFACE ................................................................ 127
10.4.1. General Settings ......................................................................................... 127
10.4.2. Subversion Access Control ......................................................................... 128
10.4.3. Subversion Email Notification ..................................................................... 130
10.5. A TYPICAL SUBVERSION LIFE CYCLE ........................................................................ 130
10.5.1. Logging In ................................................................................................... 131

10.5.2. Importing Existing Source Code ................................................................. 131
10.5.3. Checking Code Out ..................................................................................... 132
10.5.4. Updating the Source Code .......................................................................... 133
10.5.5. Examining your Changes ............................................................................ 133
10.5.6. Committing your Changes (project team) ................................................... 133
10.5.7. Contributing your Changes (other users) .................................................... 134
10.5.8. Exporting and Packaging ............................................................................ 135
10.6. SUBVERSION FOR PROJECT ADMINISTRATORS .......................................................... 136
10.6.1. Subversion Hook Scripts ............................................................................. 136
11. Document Manager ........................................................................................................ 137
11.1.STRUCTURE .............................................................................................................137
11.2.ACTIONS ..................................................................................................................138
11.2.1. New Document ........................................................................................... 138
11.2.2. New Folder .................................................................................................. 140
11.2.3.Properties....................................................................................................141
11.2.4.Notifications................................................................................................142
11.2.5.History.........................................................................................................142
11.2.6.Update........................................................................................................143
11.2.7. New version ................................................................................................ 143
11.2.8.Permissions................................................................................................144
11.2.9.Move...........................................................................................................145
11.2.10.Delete........................................................................................................146
11.3.ADMINISTRATION ......................................................................................................146
11.3.1.Permissions................................................................................................147
11.3.2. Display preferences .................................................................................... 147
11.3.3.Properties....................................................................................................147
12. Test Manager ................................................................................................................... 148
12.1. SALOME OVERVIEW ................................................................................................. 148
12.2. CONFIGURATION AND ADMINISTRATION ..................................................................... 148
12.2.1. Salome Bug Tracker ................................................................................... 148
12.2.2.Permissions................................................................................................150
12.2.3. Salome plug-ins .......................................................................................... 151
12.2.4. Salome Preferences ................................................................................... 152
12.3. LAUNCHING SALOMETMF ......................................................................................... 153
13. Continuous Integration With Hudson ........................................................................... 154
13.1. INTRODUCTION TO CONTINUOUS INTEGRATION .......................................................... 154
13.2. HUDSON INSTALLATION ............................................................................................ 155
13.3. HUDSON CONFIGURATION ........................................................................................ 155
13.3.1. System Configuration .................................................................................. 155
13.3.2. Hudson Plug-ins .......................................................................................... 157
13.4. HUDSON JOBS CREATION AND CONFIGURATION ........................................................ 157
13.4.1. CVS and Subversion ................................................................................... 158
13.4.2. Builds Schedule .......................................................................................... 158
13.4.3. Build configuration (steps) .......................................................................... 159
13.4.4. Post-build Actions ....................................................................................... 159
13.5. INTEGRATION IN CODENDI ........................................................................................ 160
13.5.1. Hudson Service ........................................................................................... 160
13.5.2. Hudson Widgets .......................................................................................... 162
13.5.3. Hudson References .................................................................................... 165
14. Wiki Service .................................................................................................................... 167
14.1. WIKI OVERVIEW ....................................................................................................... 167

14.1.1. Wiki Definition ............................................................................................. 167
14.1.2. Wiki Page Formatting .................................................................................. 167
14.1.3. Linking and Creating Pages ........................................................................ 167
14.1.4.Searching....................................................................................................168
14.2. CODENDI WIKIS ....................................................................................................... 168
14.2.1. Wiki Creation ............................................................................................... 168
14.2.2. Wiki Permissions ......................................................................................... 168
14.2.3. Examples of Wiki Usage ............................................................................. 168
14.2.4. More Documentation ................................................................................... 169
15. Communication Services ............................................................................................... 170
15.1. MAILING LISTS ......................................................................................................... 170
15.1.1.Creation......................................................................................................170
15.1.2.Administration.............................................................................................171
15.1.3. (Un)Subscription, Archive and Preferences ................................................ 171
15.2. NEWS SERVICE ........................................................................................................ 171
15.3. WEB FORUMS .......................................................................................................... 172
15.4. INSTANT MESSAGING PLUG-IN .................................................................................. 172
15.4.1. Jabber Related Information on the Codendi Web Page ............................. 173
15.4.2. Jabber Client Configuration ........................................................................ 173
15.4.3. Multi-User Chat Room (MUC) ..................................................................... 174
15.4.4. MUC Room Logs ........................................................................................ 176
16. Survey Manager .............................................................................................................. 178
16.1. PUBLISHING A SURVEY ............................................................................................. 179
16.2. ADMINISTERING SURVEYS ........................................................................................ 180
16.2.1. Survey Structure ......................................................................................... 181
16.2.2. Creating or Editing Questions ..................................................................... 181
16.2.3. Creating or Editing a Survey ....................................................................... 182
16.2.4. Reviewing Survey Results .......................................................................... 183
17. Project Web Site ............................................................................................................. 185
17.1. VISITING A WEB SITE ............................................................................................... 185
17.2. WEB SITE CREATION ............................................................................................... 185
17.2.1. Directory Structure and Location ................................................................ 185
17.2.2. Web Site Scripting with PHP ....................................................................... 186
17.2.3. Web Site Publishing .................................................................................... 186
17.3. REFERENCING THE CODENDI SITE ............................................................................ 187
18. Other Services ................................................................................................................ 189
18.1. SHELL ACCOUNT ...................................................................................................... 189
18.2. FTP ANONYMOUS STORAGE SPACE ......................................................................... 189
18.3. SOAP API .............................................................................................................. 190
18.4. CODENDI COMMAND LINE INTERFACE (CLI) .............................................................. 190
18.5. CODENDI ECLIPSE PLUGIN ........................................................................................ 190

List of Figures
1. The Codendi Home Page ................................................................................................... 2
2. The Codendi Home Page, with a different theme (with tabs) ............................................. 3
3. Codendi Web Page Flow Chart .......................................................................................... 5
4. Software Map sample browsing .......................................................................................... 6
5. List of Code Snippets in the 'HTML Manipulation' category ............................................... 8
6. The Personal Page of a Codendi user ................................................................................ 15
7. A sample Project Summary Page ....................................................................................... 23
8. A Sample Project Administration Page ............................................................................... 27
9. A sample project members permission table ...................................................................... 34
10. User Group Management Page ........................................................................................ 35
11. User Group Edit ................................................................................................................ 37
12. Sample Access Log .......................................................................................................... 43
13. Tracker Welcome Screen ................................................................................................. 45
14. A sample artifact submission screen (the artifact is of type "bug" here) ........................... 46
15. A sample Tracker browsing screen .................................................................................. 50
16. Header of Tracker Update screen (artifact fields) ............................................................. 53
17. Follow-up comments attached to an artifact ..................................................................... 54
18. Artifact Dependencies ....................................................................................................... 56
19. Permissions d'un artefact ................................................................................................. 57
20. Artifact History .................................................................................................................. 58
21. Artifact Selection screen for the artifact mass change ...................................................... 59
22. Header of Artifact Update screen for the artifact mass change ........................................ 59
23. CC list of Artifact Update screen for the artifact mass change ......................................... 60
24. Creation of a new tracker (here a defect tracking system) ............................................... 65
25. Tracker Administration - Top Level Page ......................................................................... 68
26. A sample tracker permissions screen ............................................................................... 70
27. Field Set screen of a project tracker ................................................................................. 72
28. Field Usage screen of a project tracker ............................................................................ 75
29. Tracker field usage settings .............................................................................................. 77
30. Tracker field list with user definable values ...................................................................... 78
31. List of values for the "Resolution" field ............................................................................. 79
32. Setting a field value .......................................................................................................... 80
33. Linux Dependencies ......................................................................................................... 81
34. MacOS X Dependencies .................................................................................................. 82
35. MS Windows Dependencies ............................................................................................. 83
36. NetBSD Dependencies ..................................................................................................... 84
37. Version 2.0 depends upon Linux and NetBSD systems ................................................... 85
38. Proposed versions for Linux ............................................................................................. 85
39. Proposed versions for MacOS X ...................................................................................... 86
40. Proposed versions for MS Windows ................................................................................. 86
41. Proposed versions for NetBSD ......................................................................................... 86
42. Definition of Canned Responses ...................................................................................... 87
43. Example of a list of tracker reports ................................................................................... 88
44. Setting a Tracker Report ................................................................................................... 90
45. Configuration of the Personal Notification Matrix .............................................................. 95
46. The File Release Structure ............................................................................................... 97
47. The File Release screen of the Codendi Administration project ....................................... 98
48. The File Release screen of the Codendi Administration project, when you are admin .... 100
49. Package Edition Screen of the CLI package, in the Codendi Administration project ....... 101
50. The release update screen of the Codendi project ........................................................... 102

51. Browsing the CVS repository - A sample session ............................................................ 109
52. Querying the CVS tracking database of a given project ................................................... 110
53. The detail of an atomic CVS commit ................................................................................ 111
54. A Typical Software Development Life Cycle on Codendi ................................................. 113
55. Browsing the Subversion repository - A sample session .................................................. 125
56. Querying the Subversion tracking database of a given project ........................................ 126
57. The detail of an atomic Subversion commit ...................................................................... 127
58. A Typical Software Development Life Cycle on Codendi ................................................. 131
59. Folders and subfolders ..................................................................................................... 137
60.Actions..............................................................................................................................138
61. Create a new document .................................................................................................... 139
62. Create a new folder .......................................................................................................... 141
63. Display and edit properties ............................................................................................... 142
64.Notifications......................................................................................................................142
65. See a document history .................................................................................................... 143
66. Update a link ..................................................................................................................... 143
67. Create a new version for embedded file ........................................................................... 144
68. Define permissions ........................................................................................................... 145
69. Move a document ............................................................................................................. 146
70. Shortcuts to move a document inside a folder .................................................................. 146
71. Salome tracker configuration ............................................................................................ 149
72. Salome permissions configuration .................................................................................... 151
73. Salome plug-ins configuration .......................................................................................... 152
74. Salome preferences configuration .................................................................................... 153
75. Launch Salome ................................................................................................................. 153
76. External Tools Configuration ............................................................................................ 156
77. Link Hudon job with your project ....................................................................................... 161
78. Hudson jobs associated with your project ........................................................................ 161
79. "My Hudson Jobs" Widget ................................................................................................ 162
80. "Jobs Overview" Widget ................................................................................................... 162
81. "Lasts Builds" Widget ........................................................................................................ 163
82. "Test results" Widget ........................................................................................................ 163
83. "Tests Trend" Widget ........................................................................................................ 164
84. "Builds History" Widget ..................................................................................................... 165
85. "Last artifacts of the Build" Widget .................................................................................... 165
86. Multi-User Chat Room in the web interface of Codendi .................................................... 175
87. Survey Manager Welcome screen .................................................................................... 178
88. A sample survey taken from the Codendi project ............................................................. 180
89. Survey Manager Administration screen ............................................................................ 181
90. Survey Results .................................................................................................................. 183
91. Codendi plugin for Eclipse IDE ......................................................................................... 190

Codendi User Guide

CHAPTER 1

Introduction

The goal of the Xerox Code eXchange Initiative (Codendi) is to transpose and apply the princi-
ples of Open Source into our own corporate environment. Establishing collaborative software
development and project management practices as one of our core software engineering values
will improve the quality of our software and the productivity of our development teams while pro-
viding a rich, attractive and cost efficient.

The Codendi initiative is supported by an internal Web site of the same name that is available at
http://www.codendi.org/.

The Codendi User Guide was written not only to describe the Codendi features and services; it
is also packed with tips and guidelines to help you get the most out of Codendi and manage
your project in an optimal way.

We hope that you enjoy working with Codendi. If so, keep talking about the Codendi initiative to
fellow programmers, project managers and managers. Codendi users are our best advocates.
Also keep in mind that this User Guide is yours and, following source code sharing principles,
we welcome your corrections and contributions.

Enjoy Codendi!

The Codendi Team

1

Codendi User Guide

Figure 1. The Codendi Home Page

2

Codendi User Guide

Figure 2. The Codendi Home Page, with a different theme (with tabs)

3

Codendi User Guide

CHAPTER 2

Codendi Site Overview

Codendi is a Xerox Web Site available at http://www.codendi.org/. To browse the Codendi site
use your favorite Web Browser 1. Codendi is a rich site and the Codendi User Guide is going to
guide you through all the services that the Codendi site has to offer. In order to help you find
your way in the Codendi services gallery, Figure 3 [page 5] gives a broad overview of the ser-
vices available as well as a flow chart showing how to access a given service.

2.1 Codendi Home Page
The Home Page is divided in 4 parts (see Figure 1 [page 2]):
1. The Codendi Main Menu: on the left hand side of the screen or at the top depending
on the graphical theme in use.
2. Codendi Short Introduction: the upper central part gives you a brief but pivotal intro-
duction to the Codendi initiative and a series of links to must read documents
3. Codendi Latest News: The lower central part shows the last 10 pieces of news re-
lated to Codendi hosted projects or to the Codendi site.
4. The Codendi Dashboard: The right hand side of the home page shows a series of
statistics about the overall activity of the Codendi Site.

2.2 The Codendi Main Menu
The Codendi main menu is a permanent piece of information that you'll always see on your
screen wherever you are in the Codendi site. Its content can vary according to where you and
who you are. In other words it is context sensitive. Let's take 2 examples:

• If you are visiting the Codendi site as an anonymous user the upper part of the menu in-
vites you to login or to create a new account whereas if you are logged in you'll be given
access to other functions like Logout, Account Maintenance, Personal Page, etc.
• Similarly if you decide to visit a given project hosted on Codendi, the menu at the top of
the screen will also show you the list of services available for this project.

In the rest of this section we only review those items that are permanent and context indepen-
dent. Other menu items are described later in the document in the related service description.

1Codendi uses standard HTML and only a little bit of Javascript. It is known to work well with Netscape 6.x and 7.x,
Mozilla/Firefox as well as IE 5 or 6. Other Web Browsers like Opera or Konqueror work as well. Codendi uses very little
graphic material and is therefore browsable by specific text only browser like those used by visually impaired people.
4

Codendi User Guide

Figure 3. Codendi Web Page Flow Chart

5

Codendi User Guide

2.2.1 Software Map (or Project Tree)
The Software Map is a pivotal service in Codendi that you can (should) use to determine if there
are some pieces of software that you can re-use for your own work. The Software Map is one of
the 2 ways by which you can search for existing software projects. The other one relies on the
Search Facility.

Figure 4. Software Map sample browsing

When a project is created it is classified by the project creator according to 7 criteria:

• Development Status: How mature your project is (alpha, beta, stable,...)
• Environment: in which environment your software is being used (Web, Win32, X Win-
dow, text mode,...)
• Audience: The target audience of your software (developers, end-users, system admin-
istrators,...)
• License: License of your software. In most cases this is going to be the Xerox Code ex-
change Policy
• Operating System: Operating system(s) your software runs on
• Programming Languages: the programming languages you used to develop your soft-
ware
• Topic: The field of use of your project. This criteria describes the area in which your
software operates (Printing, Scanning, Information Technology,...)

Each criterion can have up to 3 values for a given project (e.g. you can select up to 3 program-
ming languages for a given project). Values of the various criteria are taken from a list of prede-
fined values defined by the site administrator. The "Topic" criterion reflects the domain covered
by your project (Printing, Scanning, Information Technology, etc.) and it follows a hierarchy of
domains and sub-domains that the Codendi Team constantly refines as more projects are com-
6

Codendi User Guide

ing.

Using the Software Map you can browse Codendi hosted projects according to any of these cri-
teria. As you explore the map, projects matching the criteria are listed on the screen with their
name, description, creation date, activity percentile, and other information. The values of the 7
criteria for a given project are listed right after the project name and description. Notice that next
to each criteria value is a [Filter] hyperlink. Clicking on any of these filters will result in restricting
the project list to those that match the filter. Codendi project templates or test projects (see Sec-
tion 6.5 [page 27]) are not listed in the Software Map.

A Software Map browsing sample is shown on Figure 4 [page 6]. In this example, the user has
first opened the Programming Languages Criteria and then selected C as a language of choice.
This probably led to a large number of projects and so she then decided to narrow the set of
projects by specifying 2 additional filters: the first one specifies that the Development Status
must be Production-Stable and the second one requires that the projects runs on the SunOS/
Solaris operating system.

As a result of this multi-criteria screening, the user ends up with a list of 9 projects (only the first
one is shown on Figure 4 [page 6] to save space). Filters have another interesting property: they
are sticky. It means that if you decide to browse the projects from another angle (say by opening
the Topic folder), the selected filters will constantly apply. In order to release the search con-
straint you must explicitly remove the filter by clicking on the [Remove this Filter] link in the up-
per part of the screen.

TIP
If you repeatedly execute the same browsing operation on the Software Map you can save it in your
Personal Page. To do this, first execute your software map request as explained above and when
you are happy with the selection criteria, click on the Bookmark This Page item in the Codendi Main
Menu. This will make a new link appear in your Personal Page that you can then edit to give it an ap-
propriate description.

2.2.2 The Code Snippet Library
A project hosted on Codendi has the ability to use a large spectrum of services. However not all
pieces of software worth sharing require such a rich environment. Sharing a very short piece of
source code like a macro, a function or a shell script has to be quick and easy. This is precisely
the role of the Code Snippet Library.

The Code Snippet Library can be accessed via the Codendi Main Menu on the left hand side of
the screen under the Software section (see Figure 1 [page 2])

Code Snippet Browsing
The welcome page of the Code Snippet Library classifies the code snippets by category and by
programming languages. The figures next to each label indicate the number of code snippets
available in each category.

You can browse code snippets in 2 different ways:

• Navigate through the categories or programming languages classification
7

Codendi User Guide

• Use the Search box in the Codendi Main menu on the left hand side or on the upper
right corner of the screen. Keywords typed are search in the code snippet title and in the
code snippet description.

Matching snippets are shown in a list along with their code snippet ID number, title and short de-
scription. If you navigated through the categories, there is also a detailed description as well as
the author's name. Please note that by clicking on the author's name you can immediately send
a question or a suggestion to the author of the code snippet.

Figure 5. List of Code Snippets in the 'HTML Manipulation' category

Code Snippet Submission
To submit a new code snippet click on the "Create a new Snippet" link in the Code Snippet
Menu at the top of the screen. Provide the code snippet title and description. You can use Web
locations (URLs) in the description field. Codendi will automatically turn them into hyperlinks in
the final version. Also provide the code snippet type, programming language and category as
requested. Should a category or a programming language be missing when you submit a new
code snippet please contact the Codendi team.

It is highly recommended that you provide a version number as well. This version number is a
free text field and can have any kind of value. Using a version number is useful if you want to
post a newer version in the future. We also recommend that you indicate the same version num-
ber in the source code associated with the snippet so that Codendi users can determine
whether they already have the latest version the next time they visit the Code Snippet Library.

The code snippet itself can be submitted either by simply copy-pasting the source code in the
text area or by uploading a file. We do recommend that you copy-paste the source code to
make it directly visible when users browse the Code Snippet library.

However there are cases where it is ok to upload non human readable files. Typical examples
are when your code snippet is a made of several files that you may want to deliver in the form of
an archive (zip or compressed tar). Another example is when the code snippet is not human
readable: simulation software (e.g. LabView) use proprietary and non human readable format
for their source files. In any case do not post pure binary code like compiled C, C++,Java,... The
8

Codendi User Guide

Code Snippet Library, like Codendi, is about sharing and reusing software code not binary.

Updating a Code Snippet
To update a code snippet with a newer version of the source code, select the original code snip-
pet either by browsing the code snippet category or by using the search mechanism. Click on
the Code Snippet in the result list and proceed to the "Submit a new version" link at the end of
the screen. Provide a change description, a new version number and copy-paste the source
code associated with the new version.

Please note that even though this is still the same code snippet, Codendi assigns a new code
snippet version ID number to each version. So referencing a new version in a Code Snippet
Package (see section Grouping Code Snippets below) will require that you delete the old ver-
sion and add the new one.

Deleting a Code Snippet
Select the code snippet as indicated above. Then click on the appropriate code snippet in the
result list. From here you can click on the waste basket icon ( ) next to the code snippet ver-
sion to delete one or several versions of the code snippet.

Grouping Code Snippets
If you have submitted several code snippets that relate to the same topic, are written in the
same language and belong to the same code snippet category it might be a good idea to group
them together under a common umbrella. This is what Code Snippet Packages are for.

To create a code snippet package click on the "Create a Package" item in the Code Snippet
Menu at the top of the screen. Provide a title, a description, type, category and version as re-
quested. After you submit the form, a new window will pop up asking you for the ID numbers of
the Code Snippet versions that must be added to the package. So before you create a package
make sure you have the code snippet version ID numbers available.

Please note that there is a Snippet ID and a Snippet Version ID. If you upload a new version of
a snippet, the Snippet ID won't change, but the Snippet Version ID will. So when you create
snippet packages, make sure that you use the Snippet Version ID.

Updating a Code Snippet Package
Like code snippets, packages can be updated. To update a package just proceed as for an ordi-
nary code snippet. First search for it, select it and finally click in the Edit icon. From here you
can add/delete code snippet to/from the package. If you want to update the package with a new
version of a code snippet, first delete the old version and add the new one which has its own
specific code snippet version ID (see Section [page 9]).

2.2.3 Help

Help Index
Codendi comes with a comprehensive User Guide that fully describes all the Codendi tools and
services. A click on the "Help Index" link will direct you to the table of content of the Codendi
9

Codendi User Guide

User Guide. The same user guide is used throughout the Codendi site in the "Help" links that
you'll find in almost every menu appearing on Codendi. A PDF version of the integral user guide
is also available in the "Site Documentation" section.

Site Documentation
The "Site Documentation" pointer is the entry point to the Codendi documentation. The Codendi
documentation is entirely managed via the Document Manager (see ???) service of the Codendi
project, which is of course hosted on Codendi. The documents on this page cover all the Co-
dendi site. It includes presentation material, the user guide and other important documents.
Read them carefully.

Codendi Developers Channels
One of the top priority objectives of the Codendi site is to become a discussion forum for the
software developers regardless of the organization they belong to and the country they work in.

To this end the Codendi Team has created a series of mailing lists (called Developers Chan-
nels) where anybody, including non-Codendi users, can subscribe. Each channel is dedicated to
a given software related topic. The creation of a new channel is under the responsibility of the
Codendi Team. If you want to create a new developers channel please contact the Codendi
Team at codendi-contact@www.codendi.org.

The Developers Channels managed on Codendi offer a number of interesting features:

• Subscription and Un-subscription are entirely user driven and it can be done through the
Codendi Web interface without any assistance.
• All messages posted to the channel are archived forever and can be browsed at any
time. (In the future they will probably be searchable as well).
• Subscribers can decide to receive digests from the mailing list rather than individual
messages.

Codendi Discussion Forums
Discussion Forums are an alternate way to keep in touch with the Codendi community. The Co-
dendi Discussion Forums were created primarily as a communication vehicle between the Co-
dendi users and the Codendi Team. These are general purpose Forums where you can ask for
Help with Codendi, suggest new features, new categories for the software map, etc.

These Forums are entirely Web based which means that you have to use the Codendi Web in-
terface to post and read user messages. However Forums also offer the ability to be monitored,
which means that all traffic will be sent to you via e-mail.

Contact Us
In addition to the Discussion Forums, you can always use the "Contact Us" link to get in touch
with the Codendi Team.

Do not hesitate to bug the "Contact Us" link. We are here to help.

10

Codendi User Guide

2.2.4 The Search Facility
Codendi allows you to search almost any piece of Codendi information through a keyword
search mechanism. When you are on the Codendi Home Page you can search for keywords in
the following resources:

• Software Projects: a match is attempted with project names as well as their short and
long description. This search mechanism is very complementary with the Software Map
(see Section 2.2.1 [page 6]). Notice that a private project will never appear as a search
result.
• Code Snippet Library: Code snippets are small pieces of code that you can post on
Codendi (see Section 2.2.2 [page 7]) along with a description. You can search this de-
scription by keywords are see if there are code snippets that you can re-use to ease
your job.
• People: keywords will be searched in the Codendi user database and matched against
the user's login name, real name and e-mail address.
• Wiki: Wiki is a collaborative authoring tool (see Chapter 14 [page 167]). You can perform a
full text search by keywords in wikis.
• This tracker: If you enter any tracker in any Codendi project, the "This Tracker" item will
show up in the search box, allowing you to actually search this tracker database.

2.3 The Codendi Dashboard
The Codendi Dashboard resides on the right hand side of the Codendi Home Page. It is a sort
of a fish-eye view of the global Codendi activity. Several indicators are available:

• Codendi Statistics: give the total number of hosted projects (excluding those that have
a private status, as well as template and test projects), the total number of registered
users, the total number of software packages downloaded and the total number of Web
pages browsed by Codendi users since the site opening.
• Top Project Downloads: shows which software projects were downloaded the day be-
fore and how many times.
• Newest Releases: shows a list of the most recent software releases (also known as
new versions) that have been posted on the Codendi site by the various projects. If you
want to keep aware of new incoming releases visit this page on a regular basis. Co-
dendi also allows you to monitor the new software releases posted by a given project.
To do so go to the Project Summary page of this project by clicking on the project title
and then select the monitor icon ( ) next to the release name. Once you monitor a
project release, e-mail notification will be sent to you whenever the project team posts a
new software release.
• Newest Projects: the last 10 registered projects. Looking at this part of the dashboard
on a regular basis will help you to keep informed on the new projects hosted on Co-
dendi.
• Most Active This Week: the 20 most active projects over the past 7 days on a scale
from 0 to 100%. The magic formula that we use behind the scene to compute this rank-
ing is a weighted sum of the activity observed in the various projects services. It takes
many things into account: the number of CVS/Subversion transactions, the number of
bugs and tasks submitted or modified, the number of file releases, etc. Looking at this
list is an excellent way to see which projects are actively working on Codendi.

As a conclusion, we strongly advise you to visit the Codendi Home Page on a regular basis for it
11

Codendi User Guide

gives you an excellent idea of what is going on in terms of software development across Xerox.

Bookmark This Page: Make Codendi your browser home page :-)

12

Codendi User Guide

CHAPTER 3

Becoming a Codendi Citizen

3.1 Classes of Citizens
Before we go further into the user registration process it is worth reviewing the various types of
Codendi citizens. There are basically 4 of them:

• Anonymous Users: when you first visit the Codendi site you are typically an anony-
mous user. Anonymous users can browse the Codendi site but many of the Codendi
services or Codendi resources cannot be used or accessed by an anonymous user (e.g.
source code access is not possible, all the monitoring facilities aren't either, etc.). So we
strongly advise you to become a registered user to take full advantage of the Codendi
site.

• Registered Users: once you have created your own account (see below) you can use
your login/password to authenticate yourself with Codendi. Registered users have ac-
cess to all Codendi projects including source code unless the project administrators de-
cided otherwise. And since the system knows about you, it enables you to customize
your view of the system through your Personal Page, monitor Forums, software release,
receive support request follow-ups, site updates and many other useful things.

• Project Members: users who are actively working on a Codendi hosted project. To be-
come a project member, you must first become a registered user and then ask a project
administrator to include you in the project members. Most of the time project members
are part of the project team but are not limited to software developers. They can be in
charge of the support activity, the project documentation or the project management.
Project members can be granted different rights by the Project Administrator according
to their role in the team (see Chapter 6 [page 25] for more details).

• Project Administrators: registered users who create a new Codendi project are
elected as the first Project Administrators. Project Administrators have full rights over
their projects except project deletion - a very unusual operation - that can only be done
by a Codendi Team member. In the course of the project life, the initial project adminis-
trator can grant (or revoke) the status of project administrator to any project member.

• Restricted Users: users who are project members, or even project administrators, but
with restricted access rights: they cannot access pages from projects they are not mem-
ber of. This special role is only enabled on Codendi servers in heterogeneous environ-
ments where corporate users and external consultants share the same server.

3.2 User Registration
13

Codendi User Guide

As suggested above, the first thing to do for a newcomer is to create her own account on Co-
dendi. Becoming a registered Codendi user doesn't imply any commitment on your part to host
any of your software projects on Codendi. It simply gives you more freedom when you browse
the site and allows Codendi to serve you with personalized information.

Registering on Codendi is quick and easy:
1. Select the "New User" link
2. Give the following information (all items marked with an asterisk are mandatory):
a. Login Name: your user name. On some Codendi systems that are connected to
an enterprise directory you may have to use a pre-defined user name.
b. Password: 6 characters minimum and repeat it twice to make sure you didn't
make any typo in the first occurrence
c. Full Real Name: what's your name again?
d. E-mail Address: depending on the site configuration valid email addresses may
be limited to those in the Xerox domain (or Xerox affiliated domains). Make sure
your email address is correct or you won't receive the registration confirmation
message in your mailbox and won't be able to complete the registration process.
e. Time Zone: choose the time zone you live in. Choosing the correct time zone is
really important. Behind the scene Codendi stores all time stamps in GMT time.
Choosing the right time zone allow s Codendi to translate all time stamps to your
local time on the Web pages.
f. Site Updates: check this box if you want to receive site updates from the Codendi
Team. This is a low traffic distribution list and we strongly advise you to check this
box (default). You'll receive e-mail from us about the site maintenance, the impor-
tant event in the life of the site, Codendi presentation/training announcement and
the Codendi newsletter.
g. Additional Community Mailings: check this box if you want to receive notifica-
tion about less important events. You can safely check this box as well if you want
because we seldom use it. So we assure you that you won't be overwhelmed with
tons of e-mail.
3. Shortly after you validate the registration form you will receive a message in your mail-
box which includes a URL. Clicking on this URL will bring you to a Codendi form asking
for your login/password again. If they match then your account is validated and you are
now logged into the Codendi site.

Tip: Codendi servers with LDAP authentication
Your Codendi server might be set up to use an external LDAP directory for authentication. In this
case, the registration phase is even simpler: simply type your LDAP login and password, and the
system will automatically extract most of the required information from the LDAP directory: email ad-
dress, real name, etc.

This 2-step registration process has been put in place for security reasons. Assuming people
create their account with an alien e-mail address while they have access to the Intranet, they
won't be able to validate their account from the outside because the Codendi machine is behind
the firewall. Therefore, an account cannot be validated from outside.

Tip: What if I loose my password or my login name?
Don't Panic and, above all, do not create a new account! Go to the Codendi Login Page and click on
the [Lost your password?] link. You'll be asked your login name and from that Codendi will send you
an e-mail message with an embedded URL. Click on this URL and give your new password.

14

Codendi User Guide

And what if I loose both my login and password? Gee! In this case use the search box and, assum-
ing that you gave your full real name when you first registered, search for your last name and see if
you can find your login again in the list of selected users. If so, apply the previous procedure. If not
then contact us!

3.3 Login and Personal Page
To log into the Codendi site, go to the Codendi Site at http://www.codendi.org and click on the
"Login" link. If you typed your login and password OK, Codendi presents you with your Personal
Page (Figure 6 [page 15]). At any point in time you can return to your Codendi Personal Page by
selecting the "My Personal Page" in the upper part of the Codendi Main Menu.

Your Personal Page is a crossroad from which you can quickly go to Codendi workplaces and
information spaces. You'll see bugs and tasks assigned to you in the various projects you be-
long to. In addition the bug section also shows those bugs that you have submitted including to
foreign projects. By doing so, Codendi allows you to follow the evolution of bugs that you have
reported and you might be impatient to see fixed.

Figure 6. The Personal Page of a Codendi user

Codendi allows you to personalize your page to fit your needs. The content of your page is
made of widgets. All widgets can be moved (1), collapsed or closed (2). Some of them can pro-
vide an rss feed (3) or preferences can be set (4).

New widgets can be added through the link "Add widgets" (5). Here is an incomplete list of
available widgets for the personal page:

• Monitored File Packages lists packages that you are currently monitoring, by project.
To cancel any of the monitored items just click on the trash icon ( ) next to the item la-
bel.
15

Codendi User Guide

• Monitored Forums lists forums that you are currently monitoring, by project. To cancel
any of the monitored items just click on the trash icon ( ) next to the item label.

• My Artifacts lists artifacts you have submitted or assigned to you, by project.

• My Bookmarks lists your favorite bookmarks (your favorite pages in Codendi or exter-
nal). Note that in many cases Codendi uses URL with enough embedded information to
bookmark sophisticated items like Software Map browsing, typical search in your project
Bug or Task database, etc ... Bookmarked items can be edited which means that both
the title of the bookmark and its destination URL can be modified.

• My Projects lists the projects you belong to. Selecting any of these projects brings you
to the corresponding Project Summary page.

• Quick Survey: On going site survey (if any) not yet taken.

• RSS Reader allows you to include public rss (or atom) feeds into your personal page.

3.4 Account Maintenance
You provided a certain amount of demographic information to Codendi when you first registered
on the Codendi site. This and other information can be modified at any time by selecting the "Ac-
count Maintenance" item in the Codendi Main Menu.

Most of the items on the "Account Maintenance" page will look obvious to you. However, we
would like to draw your attention on some of them:

• Edit My Skills Profile: a user can make his resume available on Codendi. The intent
here is to let people know about you, your technical background and your domain of ex-
pertise. Very useful to get to know each other.

• SSH shared keys: this one has to do with the Shell Account service. When you are a
registered user, the Codendi server gives you a personal shell account with the same
login/password as for the Web interface. To automate the shell login you can share a
public encryption key with Codendi and use the secure shell SSH to access Codendi in-
stantly without having to type a password. More on that in Section 18.1 [page 189]

3.5 Preferences
Your preferences are available in My personal Page -> Preferences. Here are some of the pref-
erences you can define:

• Remember my Login/Password: by default your current login session on Codendi is
terminated whenever you stop your Web browser. When you restart your browser and
visit Codendi you will be asked for your login/password again. By checking this box you
ask Codendi to remember about your login/password forever or at least until you explic-
itly select the "Logout" item in the Codendi Main Menu. For security reasons we do not
recommend using this feature unless you are equipped with a strictly personal desktop
machine

• CSV separator: Codendi provides you export and import functionalities (See Section

16

Codendi User Guide

6.11 [page 38] for details). The import/export format is CSV format. Like CSV norm is not
implemented by the same way in each software, we allow you to change the CSV sepa-
rator, in order to fit with your preferred software! The available separators are:

• comma (,) : the default separator.

• semicolon (;) : used by default by the french version of Excel.

• tab (tab).

• CSV date format: Codendi provides export and import functionalities (See Section 6.11
[page 38] for details). The import/export format is CSV format. Like CSV norm is not im-
plemented by the same way in each software, we allow you to change the CSV date for-
mat, in order to fit with your preferred software! The available formats are:

• month/day/year : the default format (generally used in United States).

• day/month/year : used by default by the french version of Excel.
This format will be used to generate the exported artifacts, and will also be used when
importing. Then, don't forget to check your dates value before importing. They should be
the same format as defined in your preferences.

17

Codendi User Guide

CHAPTER 4

Creating a New Project

So - you are a freshly registered Codendi user and you want to make your developer or project
leader life easier. In other words you want to:

• Avoid the pain and cost of creating your own project infrastructure (with servers and
backup)
• Avoid paying a premium price for commercial version control, defect tracking and task
management tools
• Quickly setup a project environment that you can share with your colleagues, your part-
ners, your contractors or your customers where ever they are while keeping your infor-
mation safe and under control.
• Make your organization globally more productive and efficient by possibly letting others
re-use your software and build on it.

If any of these points is appealing to you then you should definitely host your software project on
Codendi. Let's see how you can do that.

4.1 Project Registration
Before you create a new project you must be a registered user (see Section 3.1 [page 13]). You
then login and select the item "Register New Project" in the upper part of the Codendi Main
Menu.

The project registration is an easy process:

• Project Registration

Some information about Codendi Services. Just read it.

Do not forget to read and agree the Terms of Services Agreement.

• Project Name

Give the project short name and the project full name. Carefully read the restrictions that
apply to both names before you type anything. The full name can be changed at any
time in the life of the project. The short name cannot2. So think about it twice before you
make a decision!

• Project Template

You already registered a Codendi project and would now like to reuse the same configu-
2Actually it can but you have to ask the Codendi Team to do it for you.
18

Codendi User Guide

ration (services, trackers, documents, references, ...) ? Make your old project a template
project (see Section 6.5 [page 27]) and you will find it here in the list of available project
templates. Check your old project as template and your new registered project will be
staffed as you are used to. If you don't want to reuse a specific template just keep the
Default Codendi Template checked and go on.

• Project Description

This is where the rubber hits the road! Tell us about your project. Give an accurate de-
scription. This is really important if you want to maximize the chance of re-use by others.
Also list any information related to Intellectual Property like Invention Proposal or
Patents related to the software whether pending or already filed. Give the list of software
needed (whether internal or 3rd party) to make your own software run properly. And the
last field is entirely for you. Write down all the things that you consider as crucial for your
project or for the community of users.

• Project Services

You can choose which services will be activated for your project. Please note that you
will be able to change those preferences after project creation.

• Project Categorization

Please select up to three classifications for this project in each of the Trove root cate-
gories. This will help potential developers and users to find your project and engage. If
the project does not require any or all of these classification, simply select "None Se-
lected". If you used a project template that had already been classified you will find its
categories already selected here. You can change the trove categories for this project at
any time. You can categorize your project according to the seven criteria listed in Sec-
tion 2.2.1 [page 6].

• Software Policy

Most of the time the only valid choice here is the default one: "Xerox Code eXchange
Policy". As explained earlier in this document the Codendi Team assisted by Xerox
lawyers have carefully crafted the Codendi Policy and it is very unlikely that you need to
create your own. If you do you'll have to talk to us and to the Xerox Legal Department to
validate it. A number of truly Open Source licenses are also mentioned in the list. Finally
you can also choose you own licensing conditions.

• Final Confirmation

Last chance to review the submitted information before you send it to the Codendi Team
for validation. Don't worry: the project members can later update all pieces of informa-
tion shown on this page.

After you validate the project registration, the Codendi Team reviews the information you sub-
mitted and decides to approve it or not. This process can take up to 24 hours but in most cases
it's less than a couple of hours. So far all projects have been accepted so there is little to fear ...
Shortly after the Codendi Team approval you'll receive an e-mail summarizing the characteris-
tics of your project including a pointer to your new "Project Summary" page. Bookmark it in a
safe place!

19

Codendi User Guide

4.2 Post-Registration Configuration
The first thing to do after you receive the confirmation for your project registration is to visit the
"Project Summary" page (URL included in the e-mail) and finish the configuration of your
project. The 2 following actions are the most frequent ones that have to be taken after a project
is registered:

• Categorize your project in the Software Map

If you haven't done it during the project registration process, you should do it now! Your
project categorization appears on your "Project Summary" page. To categorize your
project select the "categorize it now" link and fill out the category form fields.

• Build the project team

Once a project is created, the creator is assigned the role of project administrator on this
project. It is her responsibility to define who are the project members and what their per-
missions are. This can be done by accessing the "Project Admin" page, typing the
names of all the registered users promote as team members and then define their per-
missions.

Tip: Cannot find an appropriate Topic? Contact us
Rather than putting in place a heavy hierarchy of project topics and sub-topics, the Codendi Team
has decided to start small and create only a handful of top-level topics in the hierarchy. As time goes
and as more and more projects register on Codendi we'll refine the hierarchy. If you cannot find the
appropriate topic for your project, please contact us through the "Contact Us" link in the Codendi
Main Menu or submit a request in the appropriate Discussion Forum.

20

Codendi User Guide

CHAPTER 5

Project Summary

The Project Summary page is the entry point of a Codendi hosted project. And, for any project,
it is the only page you need to know about. From this page both ordinary registered users and
project members/administrators can access all project resources and services. Unlike the
Project Administration page (see Chapter 6 [page 25]), the Project Summary page is public and
can be visited by any Codendi user including anonymous ones. In some sense the Project Sum-
mary page displays the public face of a project.

5.1 Accessing a Project Summary Page
For project members, accessing the Project Summary page of one of their projects is pretty
easy: go to your Personal Page and click on the appropriate project name.

For registered users there are several ways by which you can access the Project Summary
page of a Codendi hosted project:
1. You can use the search box and look for a project name that you know of
2. You can explore the Software Map if you know where the project is
3. You can click on the Project name if it appears on the Codendi Site statistics on the
right hand side of the Codendi home page
4. And finally you can type the Web URL to access the project page. All projects can be
accessed at:

http://www.codendi.org/projects/short_project_name

If your are thinking of visiting the Project Summary of a project on a regular basis we strongly
advise you to bookmark it in your Personal Page the first time you access the page by using the
"Bookmark This Page" link in the Codendi Main Menu. (see Section 3.3 [page 15])

The Project Summary Page is not the Project Home Page!
The Project Home Page is not the same as the Project Summary Page. The Project Summary Page
is an overview of all the software related activities and deliverables but it is not a substitute for a real
Web Site where you describe what the project is about, related links and resources, etc. Codendi
also offers a Web Site to each project. The "Home Page" item in the Project Main Menu is precisely
a pointer to this Web Site (see Chapter 17 [page 185] for more information on your Project Web Site
and how to use it).

21

Codendi User Guide

5.2 Project Summary Page Content
A sample Project Summary page is available in Figure 7 [page 23]. The page is split in several ar-
eas:

• Project Main Menu: is at the top of the page right below the Project name. The Project
Main Menu is a recap of all the services available for a given project. As you browse the
various services and resources of a given project this menu will always be visible.

• Short Description and Categorization: already described before. Next to the short de-
scription is a pointer to a longer description and to additional information provided by the
creator of the project.

• Project members and Administrators: are listed in the upper right corner of the page.
A click on a name will direct you to the user page where you can learn more about the
Codendi user and send him/her an e-mail.

• A customizeable zone (see below).

22

Codendi User Guide

Figure 7. A sample Project Summary Page

Codendi allows project admins to personalize the project summary page. The content of the
page is made of widgets. All widgets can be moved (1), collapsed or closed (2). Some of them
can provide an rss feed (3) or preferences can be set (4).

Other users than project admins will see the corresponding static page. The widgets will be the
same, in the same position, but they won't be able to modify the page.

New widgets can be added through the link "Add widgets" (5). Here is an incomplete list of
available widgets for the project summary page:

• Public Areas: this is an iconic list of all available services for this project along with
some information next to it. Click on any of this item to access a service. The role of this
area is pretty much equivalent to the Project Main Menu at the top of the screen except
23

Codendi User Guide

that it shows additional information about each of the service (e.g. total number of open
bugs, tasks, ...)

• Latest News: the last 10 pieces of news posted by the project members. Some of this
news might also be visible on the Codendi front page if the Codendi Team decided that
it was worth a site announcement.

• Latest File Release: show the list of most recent packages available for download
along with their revision. A Release Notes icon ( ) allows you to see the latest
changes and developers comments associated with this revision. Then comes the moni-
tor icon ( ). Selecting this icon will cause this package to be monitored for you. Any-
time the project development team posts a new release, you will be automatically noti-
fied via e-mail. All monitored File Releases are listed in your Personal Page and can be
canceled from this page or from the main page of the file release system.

• RSS Reader allows project admins to include public rss (or atom) feeds. For example
the reader can display a feed published by external tools used by the project (like con-
tinuous integration).

24

Codendi User Guide

CHAPTER 6

Project Administration

Whenever you enter the Project Summary page of a given project or any of its service you'll see
a menu item called Admin appears in the project menu.

Only project members can access the Project Administration page. All other Codendi users are
denied access to this part of a project.

6.1 Project Administration Menu
In addition to the project main menu that was introduced in the description of the Project Sum-
mary page, the Project Administration page has its own menu. This menu is not redundant with
the page content right below. Except for 1 or 2 items the menu and the page content give ac-
cess to distinct parts of the administration space. So pay attention to both the Page Admin
menu and the Page Admin content. In the following sections the Location label indicates where
to find the corresponding administrative function.

6.2 Adding/Removing Users
Location: Page Admin Content

User administration in Codendi is easy. Regarding the number of users to need to add, you can
use one the two following ways:

6.2.1 Add a user
To add a new member to a project team one of the project administrator just has to type the lo-
gin name of the invited member and click on the "Add User" button. If you don't know the login
name of the new project member you want to add, open a new browser window on Codendi and
use the search box in the Codendi Main Menu to search for the person's real name (first or last
name or both) and don't forget to select "People" in the Search pull-down menu. The result list
will show you the user real name and login name.

6.2.2 Import a list of users
If the number of users to add is important, one of the project team member can import a list of
users from a simple text file. In order to do it, just click the link "Import List Of Users". Then, you
can browse your local directory to select a file containing the list of users you want to import.
The file will host one user per line, by specifying her email address, or her Codendi username
(login name).
25

Codendi User Guide

johnd
steve.robinson@xerox.com
bob.johnson@xerox.com
smith3
john.smith@xerox.com

Example 1. Sample of users import file

The import process has two steps. First, it checks if the file is well formed, and it displays the
users detected to be imported. After a confirmation, the import is done and the users are added
to the project. The system doesn't perform the import in case of error (unknown user, user not
recorded in Codendi, user not active, unknown email address, etc.) If a user is two times in the
file, only one user is added and there is no error.

6.2.3 Removing a user
Removing a project member is even easier. Just click on the trash icon ( ) next to the person's
name to revoke his/her membership. Revoking membership has absolutely no effect on the his-
tory and the data integrity of the project. In other words all tracker artifacts assigned or submit-
ted by this person will continue to show up as before in the project database. Only the ability of
this person to perform project management tasks is affected. Also notice that in order to remove
a project administrator from the project member list, another project administrator must first
change the "Project Admin" flag of this user to "No" in the User Permission table. In other
words, a Project Administrator cannot be removed from the project members as long as she has
administrator privilege.

You have probably noticed that project member's name on the Project Administration page are
actually hyperlinks. On this page as well as in many other pages throughout Codendi a click on
a login name leads you to the user page where you can know more about the user (including its
location, phone/fax number, etc. extracted from the LDAP Directory in real time) and send an e-
mail message to this person directly via a Web form.

26

Codendi User Guide

Figure 8. A Sample Project Administration Page

6.3 Project Public Information
Location: Project Administration Menu

The "Edit Public Info" item of the Project Administration menu allows a project administrator to
update the Project Description Elements: these are elements provided during the registration
process.

6.4 Project Categorization

This is where you can categorize your project. You can define up to 3 values for each of the 7
criteria used in the Software Map. If you cannot find any matching value in the predefined list do
not hesitate to contact the Codendi Team.

6.5 Project Type
27

Codendi User Guide


Codendi proposes three types of projects:

• Project: This is the type of standard projects hosted on Codendi.

• Template Project: If you choose this project type new projects can reuse this projects
service configuration. When registering a new project (see Section 4.1 [page 18]) your
template project is listed as available template. When choosing your template project
then the new project will use exactly the same configuration. This includes that

• the new project is classified into the same trove categories as the template project
(see Section 2.2.1 [page 6]).
• the same services are enabled (see Section 6.6 [page 28]). Unavailable services won't
be present. Disabled services will be disabled by default.
• the same reference patterns are defined (see Section 6.8 [page 30]).
• the same project specific user groups exist (see Section 6.10 [page 35]).
• all trackers with the option "instantiate for new projects" are copied with their associ-
ated fields, field values, field dependencies, reports, and permissions (see Section
7.13 [page 67]).
• the same forums are created (but the messages are not copied).
• the documents, as well as the document tree will be present.
• the CVS admin settings are copied (preamble, tracking mode, CVS Watch Mode),
but the emails and the CVS permissions are not copied.
• the SVN admin settings are copied (preamble, tracking mode), but the emails and
the SVN access permissions are not copied.
• the file packages and their permissions are copied
Just notice that the project members of the template projects will not automatically be
part of the newly registered project. A template project does not appear any more in the
Software Map and is excluded from project statistics on the Codendi Dashboard (see
Section 2.3 [page 11]) like the newest projects listing, most active projects, etc.

• Test Project: If you just need to test what is feasible with Codendi projects use the Test
Project type for your project. Having defined that type, your project will not appear any
more in the Codendi Software Map nor on the Codendi Dashboard.

6.6 Service Configuration
Location: Project Administration Menu

The "Service Configuration" item of the Project Administration menu lists all services available
to the project. Services are items listed in the "Service Bar " on top of each page: trackers, CVS,
homepage, documentation, etc. The Service Configuration page allows a project administrator
to update, enable, disable or even create services.

There are two kinds of services:

• System services: these services are defined by the site administrator and are common
to all projects. They cannot be modified, except for their status (enabled/disabled) and
their position on the screen (see below).

• Project services: these services can be fully customized or deleted by the project ad-
28

Codendi 4.0 User Guide

Recommended

Recommended

More Related Content

What's hot

What's hot (19)

Viewers also liked

Viewers also liked (20)

Similar to Codendi 4.0 User Guide

Similar to Codendi 4.0 User Guide (20)

More from Codendi

More from Codendi (12)

Recently uploaded

Recently uploaded (20)

Codendi 4.0 User Guide