Codendi 4.0 User Guide
Upcoming SlideShare
Loading in...5
×
 

Codendi 4.0 User Guide

on

  • 21,568 views

This is the User Guide for Codendi 4.0 freely downloadable in version Labs on www.codendi.org. Enjoy it !

This is the User Guide for Codendi 4.0 freely downloadable in version Labs on www.codendi.org. Enjoy it !

Statistics

Views

Total Views
21,568
Views on SlideShare
21,565
Embed Views
3

Actions

Likes
1
Downloads
346
Comments
0

3 Embeds 3

http://lw.l3s.uni-hannover.de 1
http://www.lmodules.com 1
http://health.medicbd.com 1

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Codendi 4.0 User Guide Codendi 4.0 User Guide Document Transcript

  • 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 Location: Page Admin Content 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 Location: Page Admin Content 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 User Guide ministrator. There is one exception, the Home Page service is a system service but it can be customized with any URL. Each project hosted on Codendi has its own virtual Web server available on the Codendi site. By default the "Home Page" in the Project Service Bar links to this location (see Chapter 17 [page 185] for more details). If you want the Home Page of your project to link to some other locations on the Intranet or on the Web, simply replace the default value with your own Web location. Do not confuse your Project Home Page with your Project Summary page. The Project Home Page actually points to real Web Site whereas the Public Summary Page is just an entry point to access software related activities and deliverables. 6.6.1 Creating or Updating a Service When creating or updating a service, one has to fill the following fields: 1. Service Label: This is the label that will be displayed in the Service Bar. It should be as concise as possible. 2. Service Link: This is the URL of the service, i.e. the address the user will be redi- rected to when clicking on the service label in the Service Bar. It will be loaded in the current window. A few keywords can be inserted into the link: they will be automatically replaced by their value: • $projectname: short name of the project • $sys_default_domain: domain of your Codendi server (e.g. "www.codendi.org") • $group_id: project number. • $sys_default_protocol: 'https' if your server is configured in secure mode, 'http' other- wise. 3. Service Description: Short description of the service. It will be displayed as a tooltip when the mouse cursor is over the service label. 4. Enabled: Toggling this check box will simply disable (or enable) the service. Disabling a service just means that it no longer appears in the Service Bar and in the Project Summary page of your project but all existing data related to this service remains un- touched. In other words, re-enabling the service will restore the service in the exact same state it was when you first disabled it. See also "Deleting a Service" below. 5. Rank on Screen: this arbitrary number allows you to define the position of this service in the Service Bar relative to other services. The services with smaller values will ap- pear first. The rank values don't have to be consecutive values. It is a good idea to use values like 10, 20, 30,... so that it is easy for you to insert new services in the future without having to renumber all the services. 6.6.2 Deleting a Service Project services can be deleted. They appear with a small trash icon in the service list. Just click on this icon to suppress the service from the database. The service data are however pre- served. 29
  • Codendi User Guide System services cannot be deleted. However, you can disable them and they will not appear in the Service Bar. 6.7 Services Administration Location: Project Admin page The project administration page gives direct access to the administration of all services that have been activated for a given project. This is available in the form of a series of pointers lo- cated on the lower left part of the project administration page. Only project members with appro- priate permission are allowed to access the Codendi services administration pages (see Section 6.9 [page 33]). 6.8 Reference Pattern Configuration Location: Project Administration Menu The "Reference Configuration" item of the Project Administration menu lists all reference pat- terns available to the project. The "Reference Configuration" page allows a project administrator to update, enable, disable or even create reference patterns. 6.8.1 Reference Overview References are a powerful tool that allow cross-referencing of Codendi objects. Based on a text pattern, Codendi automatically creates hyperlinks to the desired object. When typing a follow-up comment or a commit message, any text containing the pattern "XXX #NNN" will be interpreted as a reference to the object of type XXX with ID number NNN. For in- stance, 'artifact #123' is recognized as a reference to artifact number 123, and Codendi auto- matically creates a hyperlink that directly points to the details of artifact 123. You may also reference an object that belongs to another project. In that case, use either 'XXX #group_id:NNN' or 'XXX #group_name:NNN' to reference object XXX number NNN belonging to project which ID is 'group_id' or which short name is 'group_name'. For instance, 'wiki #myproj:Welcome' is a reference to the 'Welcome' wiki page of the project 'myproj'. Some reference patterns may need more than one parameter. In this case, use '/' as a separa- tor between parameters. For example, 'wiki #Welcome/2' creates a reference to the wiki page named 'Welcome' at version '2'. There are two kinds of reference patterns: • System reference patterns: these reference patterns are defined by the site adminis- trator and are common to all projects. They cannot be modified, except for their status (enabled/disabled). Most system references are related to a specific service. For example, 'artifact', 'doc', 'file' or 'wiki' are respectively related to the tracker, document manager, file manager and Wiki services. In order to facilitate the usage of such reference patterns, they are automatically enabled and disabled when the corresponding service is enabled/dis- abled. Still, it is always possible to enable or disable those reference patterns manually. 30
  • Codendi User Guide • Project reference patterns: these reference patterns can be created, modified or deleted by the project administrator. 6.8.2 Predefined Reference Patterns Here is a list of predefined reference patterns: • art #num or artifact #num: Reference to artifact number 'num'. Note that 'num' is a system-wide number and is unique across projects. This reference links to the artifact detail/update page. In addition to the 'art' and 'artifact' keywords, artifacts may be refer- enced using the related tracker short name. For example, an artifact in the bug tracker can be referenced with bug #NNN, a support request with sr #NNN, a task with task #NNN and a patch with patch #NNN. So, when you create a custom tracker, make sure that you specify a meaningful tracker short name. • commit #num or cvs #num: Reference to CVS commit number 'num'. This is a sys- tem-wide number. The reference links to the commit details page: log message, im- pacted files, link to diff view, etc. • rev #num or revision #num or svn #num: Reference to Subversion revision number 'num'. This is a project-specific number, so if you need to reference a revision belonging to another project, you should specify the project in the reference (e.g. 'rev #myproj:123'). The reference links to the subversion revision details page: log message, impacted files, link to diff view, etc. • wiki #wikipage and wiki #wikipage/num: Reference to a wiki page named 'wikipage'. The second format allows one to specify a wiki page version. Wiki pages are project specific, so if you need to reference a page belonging to another project, you should specify the project in the reference. • doc #num or document #num: Reference to the document number 'num'. This is a system-wide number. Document numbers, or IDs, are visible in the 'Docs' main page by hovering over a document title with the mouse pointer. This reference links to the docu- ment itself. • news #num: Reference to the news item number 'num'. This is a system-wide number. The reference links to the news item page, where you can add comments. • forum #num and msg #num: Reference to forum number 'num' or to forum message number 'num'. Those are system-wide numbers. The first reference links to the forum welcome page, while the second one directly links to the message page, where you can view the message thread, and post a follow-up message. • file #num: Reference to file number 'num'. This is a system-wide number. This kind of reference allows a direct download of a file that is part of a release. File numbers, or IDs, are visible in the 'Files' main page by hovering over a file name with the mouse pointer. This reference links to the file itself, so you might be prompted for a location to store the file. You may also have to accept the project license before downloading the file. • release #num: Reference to release number 'num'. This is a system-wide number. Re- lease numbers, or IDs, are visible in the 'Files' main page by hovering over a release name with the mouse pointer. This reference links to the project file manager page, 31
  • Codendi User Guide where the referenced release is highlighted in the list. 6.8.3 Reference Usage While working in the development or the maintenance phase of a software project, it is vital to keep track of the changes made to the source code. This is what Version Control systems like CVS and Subversion do. In addition to keeping track of the source code change history it is of- ten critical to relate the changes to the artifact (a task, a defect or a support request) that led the developers to make a change in the code. And conversely, when reading the artifact description it is also very helpful to immediately see how the change was implemented. The integration of CVS and Subversion in Codendi precisely provide the Codendi users with this bi-directional cross-referencing mechanism. This is achieved through the use of references that are automatically detected by Codendi in either the follow-up comments of the project artifacts or in the messages attached to a CVS or SVN commit. The system is not limited to artifact and commit references, so you may also reference the fo- rum message where the bug was found, the documentation that describes an issue, or the file that fixes it. The system is flexible enough to allow referencing of items that are not stored in Codendi. So you may now create your own reference pattern to link to an external document manager like DocuShare, or source code management tool like ClearCase Tip: cross-reference artifacts and Source Code commits It is considered a best practice to always reference a bug, a task or a support request in any of the log message attached to a Subversion or CVS commit. Similarly when closing the related artifact (task, bug,etc.) make sure you mention the revision or commit number in the follow-up comment. You will find this extremely convenient while trying to keep track of the changes and why they were made. 6.8.4 Creating or Updating a Reference Pattern When creating or updating a reference pattern, one has to fill the following fields: 1. Reference Keyword: This is the keyword that triggers a reference creation when it is found. It should be concise and meaningful in order to facilitate readability. 2. Reference Description: Short description of the reference. It is displayed in a tooltip when the mouse cursor is over an identified reference. 3. Reference Link: This is the URL pointed by the reference, i.e. the address the user will be redirected to when clicking on a reference. The URL does not need to point to the Codendi server: you may create references pointing to external pages. The page will be loaded in the current window. A few keywords can be inserted into the link: they will be automatically replaced by their value: • $projname: short name of the project. • $group_id: project number. • $0: The keyword extracted for this reference. • $1: The first parameter in the reference. 32
  • Codendi User Guide • $2: The second parameter in the reference. • $3...$9: Up to nine parameters in the reference. Examples: • artifact #25: '$0' is 'artifact', '$1' is '25' • wiki #codendi:Welcome/1: '$0' is 'wiki', '$1' is 'Welcome', '$2' is '1', '$projname' is 'co- dendi' • myref #123:1/23/456: '$0' is 'myref', '$1' is '1', '$2' is '23', '$3' is '456' and '$group_id' is '123' • google #codendi/xerox: '$0' is 'google', '$1' is 'codendi', '$2' is 'xerox'. If you define the reference pattern 'google', with its link pointing at http://www.google.com/search?hl=en&q=$1+$2, clicking on the reference 'google #codendi/xerox' will create a google search for 'codendi xerox'. • ds #123: '$0' is 'ds', '$1' is '123'. If you define the reference pattern 'ds', with its link pointing at http://docushare/dsweb/Get/Document-$1, clicking on the reference 'ds #123' will download document '123' from your local DocuShare server. You should also note that the number of parameters is important: if the number of pa- rameters used in the text does not match the number of parameters needed by the ref- erence pattern, the reference will not be extracted. This allows one to create several reference patterns with the same keywords but different number of arguments. See for instance the 'wiki' references: 'wiki #Welcome' is a reference with one parameter, and it links to the wiki page 'Welcome', while 'wiki #Welcome/2' is another reference with two parameters that links to the wiki page 'Welcome' at version '2'. 4. Enabled: Toggling this check box will simply disable (or enable) the reference pattern. Disabling a reference pattern just means that it is no longer extracted from text fields or commit emails. Re-enabling the reference pattern is possible. See also "Deleting a Reference Pattern" below. 6.8.5 Deleting a Reference Pattern Project reference patterns can be deleted. They appear with a small trash icon in the reference pattern list. Just click on this icon to delete the reference pattern from the database. A deleted reference pattern must be re-created if you need to use it again. System reference patterns cannot be deleted. However, you can disable them so that they will not be extracted. 6.9 User Permissions Location: Page Admin Content Project Administrators have the ability to grant different permissions to different users. As an ex- ample, a project member can be granted full administration rights on the bug tracker and no rights at all on the Documentation Manager of the project. 33
  • Codendi User Guide Figure 9. A sample project members permission table Figure 9 [page 34] shows a sample project members permission table. Each column represents a service or a user capability and there is one line per project member. Let's review the column one by one: • Project Admin: A Yes/No flag stating whether a given project member is a project ad- ministrator, that is to say a project member with absolutely all rights over the project ser- vices, project deliverables and project members. Only Project Admin can access the project members permission page. • CVS Write: Right now this is always set to Yes. All project members have write permis- sion over the CVS 3repository and this cannot be changed from the current version of the Web interface. However we'll see how to deny CVS write permission to project members in the CVS chapter (Chapter 9 [page 105]). • Trackers: • None: the user has the same permissions on this tool as a non project member. • Administrator: tool administrators have full access to the administration part of the tools. As an example, they can define new artifact categories, new predefined values for artifact fields, etc. • Forums, Documentation Manager, File Manager: • None: the user has the same permissions on this tool as a non project member. • Moderator: (Forums only): A moderator has the ability to moderate the Web Discus- sion forum that is to say create/delete discussion forums for the project, delete posted messages and update the Forum status (public/private) as well as the Forum description • Editor: (Doc Mgr only): An editor has the ability to review and validate a document prior to its publication. S/he can also update and delete a document. • Administrator: (File Mgr only): A file manager administrator has the ability to upload and manage file packages and releases. S/he can also set access permissions to user groups on packages and releases, even though s/he cannot define or update user groups (only a project administrator can). 3CVS stands for Concurrent Versions System. It is one of the source code version control system offered on the Codendi site. CVS is used by hundreds of thousands of software projects all over the world. See http://www.cvshome.org for more information. 34
  • Codendi User Guide • Member of user groups: For each individual members, the column lists all the project user groups s/he belongs to. See Section 6.10 [page 35] for more information on user groups. Reminder! Don't forget to click on the "Update User Permissions" button after making any changes in the per- mission table. 6.10 User Groups Location: Project Administration Menu A user group, sometimes called a "ugroup ", is simply a group of Codendi users. User groups are used to set specific permissions to some project data (e.g. software releases and packages - see Section [page 100]). A user group is always attached to a project, but the users comprising the group do not necessarily belong to that project. 6.10.1 User Groups Management The "User Groups Admin" function of the Project Administration menu lists all available user groups, and provides a way to create new ones. Figure 10. User Group Management Page 35
  • Codendi User Guide In the list, (see for example Figure 10 [page 35]) there are two different kinds of user groups: 1. Pre-defined User Groups: These groups are defined for every project. Examples of pre-defined groups are: project_members, project_admins, registered_users, no- body, file_manager_admin, etc. These groups are dynamic: if you assign some per- mission to 'project_admins', and a new project administrator is defined, then this new user will automatically be granted the corresponding permission. 2. Custom User Groups are defined by project administrators. They are composed of a static list of users. The only requirement is that any member must be a registered Co- dendi user. This list can be modified at any time, but will not automatically be updated, except if a member is removed from the project or deleted from the system. 6.10.2 Creating a User Group When creating a user group, one has to provide the following fields: 1. Name: This is the label that will be displayed when selecting user groups in a permis- sion screen. The group name may not contain space and punctuation. 2. Description: Short description of the user group. It is only displayed in the User Group Admin page. 3. Create From: This is a quick way of pre-selecting group members: you may create a user group from scratch (Empty Group), from all Project Members or Project Admins, or from an existing user group attached to this project. The members of the selected group will automatically be added to the new group. You will be able to add or remove members on the next screen. 36
  • Codendi User Guide Figure 11. User Group Edit In the next page (see Figure 11 [page 37]), the project administrator may select individually the members of the new group. Two columns are displayed: the one on the left contains the list of all Codendi registered users, while the one on the right contains the list of users already admitted to the group. Use the two arrows between the columns to move users from one column to the other. The user interface also provides convenient ways of selecting users when the registered list is 37
  • Codendi User Guide very large: you can choose to display only those users whose login starts with a specific letter, or you may also filter the list by typing letters in the 'Filter' text box. For instance, if you type 'john', only users whose name or login contains 'john' will be displayed. Once you are done, you may click on the Submit button. The user group is created. Tip: Combining pre-defined groups with additional members Sometimes, you might want to grant some permissions to all project members and some other Co- dendi users. In this case, you might be tempted to build a user group from the list of project members and to add the other users to the group. The issue with this solution is that if new members join the project, they will have to be manually added to the group. So it is more convenient to create a group containing only the users that are not member of the project. And then, permissions should be granted to this group and to the pre-defined "project members" group. 6.10.3 Updating a User Group In order to update an existing user group, simply select it in the user group list. You will be pre- sented with the same screen as with Group Creation, where you can update the name, descrip- tion and composition of the user group. 6.10.4 Deleting a User Group User groups can be deleted. Just click on the trash icon next to the group name in the group management page (Figure 10 [page 35]) to suppress the user group from the database. Only custom user groups can be deleted. Warning Please note that if a user group was specifically granted some permission, deleting the user group might be dangerous. Indeed, if a group is the only one allowed to access a package and this group is deleted, the permission is also deleted and reset to default, so any registered user can access the package. 6.10.5 Additional Information on User Groups It is possible to know all user groups one individual project member belongs to. Simply display the User Permissions page (Section 6.9 [page 33]). However, please note that only user groups belonging to the current project are displayed. The user might also be a member of additional user groups in other projects. The bottom of the User Group Edit page (Figure 11 [page 37]) also lists all the permissions granted to this group, e.g. packages and releases this user group is granted access to. When a project member is removed from a project, or quits a project, they are also automati- cally removed from all project user groups for safety reasons. Similarly, when a user is deleted (not just suspended) by the site administrator, they are re- moved from all user groups in all projects. 6.11 Project Data Export 38
  • Codendi User Guide Location: Project Administration Menu Codendi is very appealing to many project development teams because it provides full-featured project development and management tools. A software project can be managed almost entirely from within Codendi. However a project team may need to perform some additional processing on the project data. It may need to report about progress made, what goes well or wrong, how far you are from the end date, derive statistical data, etc. It is far beyond the scope of Codendi to provide project teams with such reporting tools. There are many specialized tools on the market to generate progress reports and each project team has its favorite one. In order to satisfy this diversity of needs, the Codendi Team has developed a very efficient system that allows the project team to export the project data outside of Codendi for re-use in other tools like MS Access, Excel, Crystal Report, Open Office, or any other ad-hoc tools. Codendi provides you with 2 kinds of Data Export: • Text File Export: this is a simple text extract of your project data. It uses the well known CSV (Comma Separated Value) format. CSV is recognized by almost every Office Suite or database tool on the market. In case you want to develop your own report application most programming languages also come with a standard library that knows how to parse CSV format. • Direct Database Connection: so to speak this is not a Data Export. It is rather a direct connection to your project database through an ODBC or JDBC driver. If you want to manipulate your project data with a database tool (like MS-Access or an ODBC/JDBC application) this is certainly the best choice. 6.11.1 Exported Data Codendi gives access to the following data (details on exported fields are listed on the Codendi page): • Tracker: the artifacts data, the changes history and the artifacts dependencies can be exported for each tracker. • Survey Responses: all responses to all the surveys you have created in your project. 6.11.2 Text File Export Text File Export follow the well known CSV (Comma Separated Values) format, recognized by almost every Office Suite on the market. It can easily be imported in MS-Access, MS Excel, OpenCalc… Importing CSV Files in Excel Clicking on any of the table export link (Bug Export, Task Export,..) on the Project Data Export page generates and downloads a CSV file that you can save on your local disk or directly open in Excel or any other spreadsheet of your choice. No particular setting is required in most cases. Nevertheless, you can change the CSV separator and the date format (see Section 3.5 [page 16]) if the default one doesn't correspond with your Excel version 4. 4For example, by default, the separator for the french version of Excel is the semicolon instead of the comma. 39
  • Codendi User Guide Importing CSV Files in MS-Access Before you import external data you must first create a new database. Then go through the fol- lowing steps: • Select File Menu -> Get External Data -> Import • Choose the appropriate CSV file that you have just generated and then click on the Im- port... button. A preview of the imported table shows up on the screen • Click on the Advanced... button • Set Text Delimiter to " (double quote) • Set Date Format to YMD • Set Date delimiter to - (dash) • Then enter the name and the type of each field in the lower part of the dialog box. Re- member that this information is available on the Project Data Export page. Important Remark: you can leave the default field name (Field1,....FieldN) as well as the default Text type in most cases. However long text fields like bug/tasks follow-up comments (details field) and original comment must be declared as type Memo. Failing to do so will cause MS-Access to corrupt the imported data. In case you encounter difficulties opening your exported CSV file please consult our Tip: Excel and Regionals [page 63] Once you are done with the specification of the Import, save it by clicking on the Save As... button. For future import of the same table simply click on the Specs... button and reload your Import specification. 6.11.3 Direct Database Access To offer maximum flexibility Codendi also provides a direct access to your project data via an ODBC or JDBC database connection. Once installed on your PC the MySQL ODBC (or JDBC) driver allows a transparent access to your project specific database tables. If you use MS-Access to generate your progress or status report then the 'Direct Database Ac- cess' is the easiest way to access all of your project data in no time. Generating Your Project Database Before you attempt to access your project data with MS-Access or any other ODBC/JDBC capa- ble application you must first generate your project database. Go to the Project Admin -> Project Data Export and click on the 'Generate Full Project Database' link at the bottom of the page.The 'Generate Full Project Database' link generates a snapshot of your project data. This means you must click on the link again each time you want the project database to be up- dated with current data. If everything goes well your project database will be generated in real time and a message will tell you about the result of the generation process and what are the parameters to use to con- nect to the remote database from your desktop. Write them down and keep them in a safe place. Remark: if your project database contains several thousands of records (tasks, bugs,…), the 40
  • Codendi User Guide project database generation may take several minutes to complete. Installing and Configuring the MySQL ODBC Driver 1. First download the MySQL ODBC driver and unzip the zip archive in a temporary direc- tory of your choice. 2. Run the setup program and go through the installation process.Important Remark: On Windows you must have administrator rights to install the driver. 3. Add your project database to Windows Data Sources. For Windows users: • Use your normal user account to login. • Go to Start menu -> Settings -> Control Panel -> Administrative Tools -> Data Sources (ODBC) • Select the "User DSN" tab and then click on the "Add" button • Select the "MySQL" item from the list and then click on the "Finish" button • A dialog box will pop up asking for the database following connections parameters: • Windows DSN Name: is your choice of a name for this connection. Use "Project X Database" for instance. • MySQL host (IP or Name); www.codendi.org • MySQL Database Name: the database name is your project shortname prefixed by 'cx_' as displayed by Codendi after you generated your project database (see above) • User: the user name is 'cxuser'. • Password: No password (leave blank). • Port (if not 3306): use the default port (leave blank). • SQL command on connect: none (leave blank). Installing and Configuring the MySQL JDBC Driver For those using a Java application based on a JDBC driver, the MySQL JDBC driver and instal- lation instructions are available on the MySQL Java Connectivity page. Using Your Project Database From MS-Access Before you use MS-Access to connect to your project database make sure that the MySQL ODBC driver has been installed on your PC (see Section [page 41]) and that you have gener- ated your project database (see Section [page 40]). Then go through the following steps: • Launch MS-Access and open a new database. • In the File Menu select Get External Data -> Import. • In the File of Types pull down menu select the ODBC Databases item. • Select the Machine Data Source tab and click on your project database. • Select the tables you are interested or simply click on Select All. MS-Access will instantly (according to MS-Access standards :-) import your project data and you can then process your project data exactly as you would do for a native MS-Access database. 6.12 Tracker Artifact Import Location: Project Administration Menu 41
  • Codendi User Guide Please see Section 7.9 [page 61] 6.13 Project History Location: Project Administration Menu The Project History provides project members with Audit capabilities. Clicking on this menu item shows a list of all the changes that have taken place in the administration of the project since its creation. The list of changes reports the nature of the change (e.g. Changed Public Info, Changed Permissions, Changed Software Map, ...) , what the value was before it changed (if applicable), who changed it and when. 6.14 Access Logs Location: Project Administration Menu Depending on the configuration of the Codendi site and on the configuration of each project, source code access, documents and file release download permissions may be granted to vari- ous populations. The Access Logs provide project members with a complete audit trail of who accessed what on the project. The page shows the following information: • The downloaded File Releases. It basically reports who downloaded what file and when (date and time). The time of download is reported in local time relative to the project member time zone. • The Codendi users who used CVS to checkout or update the sources on their local desktop machine or who browsed source code via the CVS Web interface. • The Codendi users who accessed the source code through the Subversion repository or who browsed source code via the CVS Web interface. • The Codendi users who downloaded documents, except for those documents marked as being accessible to anonymous users in your Document Manager (see ???). Access Logs can be filtered out by users to show accesses from all users, project members or non project members (default). The time window can also be adjusted to show more or less ac- cess log history. 42
  • Codendi User Guide Figure 12. Sample Access Log 43
  • Codendi User Guide CHAPTER 7 Tracker Service The Codendi Tracker is one of the most powerful and versatile services offered to Codendi hosted projects. It allows for the tracking of various artifacts like bugs, tasks, requirements, etc... and a project can create as many trackers as necessary. All trackers, whether predefined at the site level or created by a project can be fully customized. 7.1 Terminology and common features Before we explain the features of the tracker service, it's worth spending some time on the ter- minology used in the tracker service as well as on some of the features that are shared by all trackers. As the Tracker Service is meant to track virtually any kind of item, the generic term "artifact" will be used throughout this document to designate items that are being tracked - be it bug, task, support request or other such type. Defining a tracker is just a matter of assigning it a name, choosing the fields that are going to be used in the tracker, and what values will be allowed in those fields. In addition to the project definable fields and field values there are other fields that are perma- nently attached to a tracker artifact. These are: • Follow-up comments: all artifacts have the full list of free text comments posted by users attached to it. • File attachment: all artifacts can have any number of files attached to it. File attach- ments generally contains supplementary information that help better characterize the nature of the artifact. • CC list: any number of users can be notified of modification to an artifact by including their Codendi user name or email address in the CC list. 7.2 Entering the Tracker Service To enter the Tracker service of a given project, first go to the Project Summary page (see Sec- tion 5.1 [page 21]) and either click the "Trackers" item in the Project Main Menu located in the upper part of the page or you can directly choose a tracker from the trackers listed in the Public Area of the Project Summary page. You will be presented with a list of trackers available for this particular project (see Figure 13 [page 45]. Select the tracker you are interested in. Entering the tracker will give you access to var- 44
  • Codendi User Guide ious tracker functions depending on the permissions you have with this tracker. You may be able to submit new artifacts, update existing ones, search and browse the artifact database or configure the tracker. Figure 13. Tracker Welcome Screen 7.3 New Artifact Submission To submit a new artifact to a given project you must first access the appropriate tracker of that project as indicated in the section above (see Section 7.2 [page 44]. When entering a given tracker you are presented with the artifact selection and browsing screen (more about this facility in Section 7.4 [page 47]). For now let's click on the "Submit a New Arti- fact" item (or whatever the artifact name is) from the Tracker Menu Bar in the upper part of the welcome screen (see Figure 15 [page 50]). 45
  • Codendi User Guide Figure 14. A sample artifact submission screen (the artifact is of type "bug" here) Figure 14 [page 46] shows a sample submission screen from one of the Codendi hosted projects. Because of the Codendi Tracker high level of customizability no two submission screens look alike. Depending on the project more or less fields may appear on the tracker sub- mission form and the name of artifact managed by the tracker may change as well. In the example provided on Figure 14 [page 46] the artifact type is a bug (also know as "defect" in corporate language). The user is asked to choose a bug Category, a bug Group, a Priority and an Assignee from a series of pull down menus. Then comes a one-line description for the bug and a longer text entry field where you can fully characterize the bug. After clicking on the Submit button, a unique ID is automatically assigned to the submitted artifact. 46
  • Codendi User Guide When submitting a new artifact, make the Summary and the detailed description as explicit as possible. Do not use a clueless summary like: "Service X doesn't work" or "Blocking problem in Document Mgr". Explain the exact nature of the artifact by giving an explicit Summary and De- scription to the person in charge. A unique ID is automatically assigned to the submitted artifact. The values proposed by a field could depend upon other field value. If javascript is activated in your browser, fields will be filtered dynamically. Otherwise, Codendi will ensure that the values you submit are correct. As explained above, artifact submission forms vary from one project to another depending on the fields used by the tracker. The submission form can also vary according to the permission level. Depending whether you are a project member or an ordinary registered user the artifact fields displayed on the screen may differ. As an example, on Figure 14 [page 46], the bug sub- mitter using the form is probably a project member because giving access to the "Assigned to" field to an ordinary registered user doesn't make much sense. It is very unlikely that users exter- nal to the project team know enough about the project organization to correctly assign the bug. That's the reason why artifact fields shown to users on the submission form can be configured in the Tracker Administration module (see Section 7.13 [page 67]) In any case don't forget to click on the "Submit" button when you are finished ! Tip: make sure your artifact hasn't yet been submitted About to submit a bug or a support request to a Codendi Project? Before you do that, make sure that others haven't yet submitted a similar artifact. To do so you can either browse the artifact database through the Artifact Selection and Browsing facility or you can use the search box in the Codendi Main Menu and search by keywords. 7.4 Artifact Browsing Codendi offers the ability to browse the artifact database according to a variable set of criteria. 7.4.1 Selection Criteria The upper part of the artifact browsing screen is devoted to the selection criteria. Figure 15 [page 50] shows the default set of selection criteria that is available when a new tracker is cre- ated. You can select bugs by Category (the module in which the bug occurred), Group (nature of the bug like Crash, Documentation Typo, ...), Status (e.g. Open, Closed, ...) and Assignee (the person in charge of the bug). Other trackers may show more, less or different selection fields depending on the configuration put in place by the tracker administrators. How selection criteria are filled out depend on their field type. The Tracker Service currently has several the following types of fields used as search criteria: Select Box Field A select box field can take its value in a set of predefined values. If you are using the simple search interface only one value can be selected at a time. If you want to select multiple values at once, use the Advanced Search facility. 47
  • Codendi User Guide There might be 2 specific values in the list of choices: "Any" matches any value in the list and "None" matches the items where no value has been assigned yet Multiple Select Box Field A multiple select box field takes it's value from a set of predefined values. While the select box field introduced above only allows one to select only a single field value, the multiple select box field allows the user to select multiple values for the same field. In search mode it behaves ex- actly like the simple select box: if you are using the simple search interface only one value can be selected at a time. If you want to select multiple values at once, use the Advanced Search fa- cility. There might be 2 specific values in the list of choices: "Any" matches any value in the list and "None" matches the items where no value has been assigned yet Text Field A Text field can contain any kind of text. There are two ways to query a text field: • Keyword search: you can type a series of space separated keywords that will ALL be searched for in the text field (including as substring in words) • Regular expression: You can also specify a MySQL Extended Regular Expression as a matching criteria (mind the surrounding /.../ !) Examples: • /^[Aa]ddition/ : matches any text field starting with either "addition"or "Addition" • /foo|bar|dim/ : matches text fields containing the string "foo", "bar" or "dim" Date Field A date criteria follows the following pattern: YYYY-MM-DD where YYYY is the year number, MM is the month number and DD is the day number. Examples: 1999-03-21 is March 21st, 1999, 2002-12-05 is Dec 5th, 2002. Integer Field An integer field can take positive or (possibly) negative values and has no decimal part. Examples: 0, 1, +2, -100… There are several ways to query an integer field. Here are the values you can specify in a inte- ger query field: • Single Integer: if you type a single integer the field will be matched against this value (e.g. 610) • Inequality: if you use >, <, >= or =< followed by an integer the search will look for integer values which are greater, lesser, greater or equal, lesser or equal to the integer value (e.g. > 120 , < -30) 48
  • Codendi User Guide • Range: if you use the "integer1-integer2" notation the search engine will look for all val- ues greater or equal to integer1 and lesser or equal to integer2 (e.g. 800 - 900 for inte- gers between 800 and 900, -45 - 12 for integers between -45 and +12) • Regular expression: MySQL Extended Regular Expression can also be used as a matching criteria (e.g. /^4.*8$/ will look for all integer values starting with a "4", ending with an "8" with any number of digits in between. Floating Point Number Field A floating point number field can take positive or (possibly) negative values, may have a decimal part or use the exponential notation for large values.. . Examples: 0, 1.23, -2.456, 122.45E+12… There are several ways to query an floating point number field. Here are the values you can specify in such a field: • Single Number: if you type a single number the field will be matched against this value (e.g. 2.35) • Inequality: if you use >, <, >= or =< followed by a number the search will look for all val- ues which are greater, lesser, greater or equal, lesser or equal to the integer value (e.g. > 120.3 , < -3.3456E-2) • Range: if you use the "number1-number2" notation the search engine will look for all values greater or equal to integer1 and lesser or equal to integer2 (e.g. -1.2 - 4.5 for numbers greater than or equal to -1.2 and lesser than or equal to 4.5) • Regular expression: MySQL Extended Regular Expression can also be used as a matching criteria (e.g. /^4.*8$/ will look for all values starting with a "4", ending with an "8" with any number of characters in between including the decimal point. 7.4.2 Favorites and Predefined Tracker Queries Tip: save and re-use your tracker queries If you often run the same queries against a tracker with the same set of selection criteria, it is proba- bly a good idea to save this query for later re-use. To do this: select the appropriate tracker report, then choose your search criteria, click on the "Browse" button to run the query. Finally click on the "Bookmark this Page" item in the Codendi Main Menu. A new bookmark will show up in your Per- sonal Page. A click on this bookmark will run the exact same query again. Your favorite queries can be saved via the Codendi bookmark mechanism as explained in the Tip box but there are also shortcuts in the Tracker Menu Bar for the most common queries. They are: • Open Artifacts: display all the artifacts that are not yet closed for this project. • My Artifacts: display the artifacts assigned to you (based on the Codendi account you are currently using) Also notice that Codendi always keeps track of the last run query. Next time you enter the 49
  • Codendi User Guide tracker welcome screen, Codendi will use the same set of selection criteria in the selection fields and display the list of matching artifacts accordingly. Advanced Search Mode At any time during the search phase, you can toggle the search mode from Simple to Advanced and vice-versa (see the Advanced Search link). The Advance Search mode allows you to select multiple values for each selection criteria. Using this mode you could search for both open and suspended bugs assigned to project members A and B. 7.4.3 Tracker Search Results Based on your selection of search criteria, Codendi runs a query against the tracker database, selects the matching artifacts, and displays them right below the selection criteria. Columns dis- played in the artifact list are entirely configurable by the project team (see Section [page 51]). Therefore, the artifact browsing screen might look completely different from the one shown in Figure 15 [page 50]. Figure 15. A sample Tracker browsing screen Artifact severity is color coded. Colors associated with severity levels may vary from one Co- dendi site to another and it is therefore shown at the bottom of the list of results generated by the search. Finally, results are listed by chunks of N artifacts where N is user-definable. If more than N artifacts are retrieved from the tracker database you are invited to click on the navigation bar to display the next or previous chunk of artifacts. 50
  • Codendi User Guide To access a given artifact from the list of results, simply click on the corresponding "Artifact ID". Artifact List Sorting By default, artifacts are sorted by ID which happens to be the chronological order in which they have been submitted and stored in the Codendi database. The list of artifacts can be sorted by any of the columns displayed on the screen by clicking on the column heading. Clicking twice on the same heading toggles the sort order between as- cending to descending. The currently displayed sorting direction is shown by a small up or down arrow next to the sort criteria right above the artifact list. One exception to this rule is for sorting by Severity. Severity being shown as a color code and not as a column per se, there is a special link at the bottom of the screen to sort the list of results by Severity. For more sophisticated sorting you can also activate the multi-column sort. In this mode sort cri- teria accumulates as you click on column headings. So you can for instance click "Severity" first and "Assigned To" second to see who in the team is assigned critical bugs and how many.At any point in the multi-column sort process, a click on one of the sort criteria displayed in the list (criteria 1 > criteria 2 > criteria 3...) will bring you backward in the sort criteria list. Using this fea- ture you can easily test various sorting strategies. Note:Sorting criteria, like selection criteria, are also saved into your preferences and the same sorting criterion is re-used in subsequent queries. Export Tracker Search Results At the bottom of the Search Result screen you have a button to export all artifacts of your search result into CSV format. Using this facility you can easily select the tracker artifacts that you want to process with other tools outside Codendi. Printer Friendly Version At any point in the process of browsing the tracker database you can click on the "Printer Ver- sion" link to display a simplified and non-decorated artifact list that prints nicely or can be copy- pasted in a document of your choice. For better readability we strongly advise you to print the list of results in landscape format. Graphical visualization You can also view graphical results of your search in the 'Charts' section. There si basely three types of graph supported : Pie, Bar and Gantt. Tracker Reports Tracker reports allow for the definition of a specific layout of the artifact search and browsing screen where one can choose the selection criteria and the columns used in the list of matching artifacts. Depending on the project, users may enjoy the ability to choose from several tracker reports by using the upper pull-down menu of the artifact browsing screen. If no project or user specific tracker report has been defined, the Codendi 'Default' report is the only one available. 51
  • Codendi User Guide Any Codendi user with access to the tracker can define her own personal report. In this case the report is a personal one and is only visible to this particular user. On the contrary, tracker ad- ministrators have the ability to define project-wide reports that all users will be able to use. See Section 7.13.8 [page 87] for more details on managing tracker reports. Graphical Tracker Reports There is also a report system for the graphical visualization service. Depending on the project, users may enjoy the ability to choose from several graphical tracker reports by using the upper pull-down menu of the 'Charts' section Any Codendi user with access to the tracker can define her own personal graphical report. In this case the report is a personal one and is only visible to this particular user. On the contrary, tracker administrators have the ability to define project-wide graphical reports that all users will be able to use. See Section 7.13.9 [page 90] for more details on managing tracker reports. 7.5 Artifact Update Selecting an artifact ID from the list generated by a search operation will bring you to a screen with all the artifact details. Depending on the permissions you have on this tracker (see Section [page 71]), the detailed view is made of text fields and menus that you can update with new val- ues. If you are an anonymous user or a registered user who does not belong to the project team, most of the fields will likely appear as immutable text. By default, non-project members cannot edit any of the artifact fields. They can only submit a follow-up comment, add themselves in the CC list or attach new files to the artifact. The Artifact Update screen is divided in several parts: Header, Comments, CC List, Artifact Attachments, Dependencies and History. 7.5.1 Header The header zone is where you'll find all the fields associated with an artifact. As shown on Fig- ure 16 [page 53], many of these fields are assigned a set of predefined values (Status, Category, Resolution) while some others have a number format (Effort) or a free text format (Summary). For more clarity, the fields are grouped in field sets. The set of fields used in a given tracker, as well as the related set of predefined values and the field sets can be configured by project mem- bers who have administration permissions on this tracker. (see Section 7.13 [page 67] for more details on the Tracker configuration). 52
  • Codendi User Guide Figure 16. Header of Tracker Update screen (artifact fields) 7.5.2 Comments As many follow-up comments as needed can be attached to any given artifact. Follow-up com- ments are free text fields where virtually any kind of information or comment can be typed in. Follow-up comments have several of interesting capabilities and extensions: • Canned Responses: it is not infrequent to see the project members in charge of the ar- tifact classification and dispatch process to post the same follow-up comments again and again. Typical examples of repeatedly posted comments are: a thank you message to the originator, a request for the originator to provide commonly missing information like version numbers or type of machine used, etc. Rather than typing the same com- ments all the time, Codendi allows project members to create a predefined set of re- sponses. Each canned response is defined by a name and by the body of the response. Posting a canned response is just a matter of selecting the appropriate response from the pull down menu in the artifact update screen and submitting the changes. Defining a new Canned Response can be done on the fly from the artifact update form by clicking on the "define a new Canned Response" link. • Comment Types: in order to avoid the exponential growth of new artifact fields to store all sorts of free text information, Codendi offers an interesting mechanism called Com- ment Types. The project team has the ability to define a list of labels that can be used to characterize the nature of a follow-up comment. This is a very helpful feature to define the nature of the information contained in a follow-up comment and to quickly identify these comments in the long list of follow-up comments. Typical examples of such com- ment types are: "Workaround" for a comment where you explain how to work around a bug, "Impacted Files" to give the list of source files impacted by the bug resolution (assuming your artifacts are bugs), "Test case" to document how to test the code in the future to make sure that this case will be tested in the future test suite, etc. Comment types are defined in the Tracker Administration module (see Section 7.13 [page 67]) • Cross-References: while typing a follow-up comment, you can use some special text 53
  • Codendi User Guide pattern to refer to other artifacts, documents, files, or CVS or Subversion commits. These pattern will be automatically displayed as hyperlinks when the follow-up comment is displayed on the screen. This is an extremely powerful and easy to use mechanism that is covered in more details in Section 7.5.6 [page 56]. Figure 17. Follow-up comments attached to an artifact 7.5.3 CC List As explained later in this chapter (see Section 7.8 [page 60]) the Codendi Tracker offers a power- 54
  • Codendi User Guide ful email notification system for those users who, at some point, were involved in the life of the artifact whether as a submitter, an assignee or as a person who posted a follow-up comment (commenter). Sometimes it is however helpful to involve other people in the email notification process even if they did not play an explicit role in the life of the artifact so far. For instance, you may want a QA contact or the originator of the artifact when different from the submitter to receive a carbon- copy (CC) of the email notifications. This is precisely what the CC List is intended for. Inserting CC names in the CC list will allow these people to receive updates notifications for this specific artifact. CC Names The CC names can be either email addresses or a Codendi login name if the user has a Co- dendi account. • Codendi login name: when the person you want involve in the notification process has a Codendi account use it in place of her email address. Using the Codendi login name give to the recipient the ability to customize the kind of update events they want to re- ceive. For more information on how to customize notification preferences for a given project see Section 7.13.10 [page 93]. • Email Address: there is no restriction on the type of email address you can type. It can be either individuals or mailing list - see Section 15.1 [page 170]. Unlike CC names entered as login names, CC names added in the form of email addresses have no customization capabilities and receive all bug updates. Adding and Deleting CC Names Several CC names can be added at once by separating them with commas or semi-column in the "Add CC" field. Using the comment field, one can also explain why these CC names were added and/or who they are. CC names addition and deletion is subject to a number of permission rules: • Adding a CC name: Anonymous users cannot add CC names. Any other Codendi user who is logged in can add CC names and the CC list will clearly show who added this en- try and when. • Deleting a CC name: users with Tracker Administrator permissions on a given tracker (see Section 6.9 [page 33]) can delete any entry in the CC list for any artifact of this tracker. All other users can delete CC entries that were either added by themselves or entries where the CC name matches their own name or email address in any Codendi projects. In other words a Codendi user has the right to undo what they have done or re- move themselves from a CC list in any tracker. 7.5.4 Artifact Attachments In addition to comments, the Codendi Tracker allows you to attach virtually any piece of infor- mation to an artifact in the form of a file. Typical examples of artifact attachments are application screen shots in PNG, GIF, JPEG or whatever image format is appropriate; it can also be core dumps, a binary image of program that crashed or even a simple text file showing a stack trace 55
  • Codendi User Guide or an error message. Artifact attachments can be of any type (image, video, sound, text, binary…) and a comment field can be optionally used to annotate the attachment. The maximum size of a file attachment is site dependent. The default is 2 MByte. 7.5.5 Artifact Dependencies The next section on the artifact update screen deals with artifact dependencies (see Figure 18 [page 56]). Codendi users have the ability to establish a dependency link from an artifact to one or several other artifacts belonging to any of the tracker of any Codendi project. This is made pos- sible by the fact that artifacts have a unique ID across the entire Codendi system. The Codendi system does not impose any semantic on the nature of these dependency links. As a project team, you are free to agree on a specific meaning for these links. It can be a cause- effect type of relationship, a duplication of information or a time dependency for a task tracker. Figure 18. Artifact Dependencies To create an artifact dependency, type one or several artifact IDs (comma separated) and sub- mit the form. The cross-referenced artifacts appear in a table right below the input field showing their description as well as the tracker and the project they belong to. To delete an artifact dependency simply click on the wastebasket icon to the right of the artifact description line and confirm or cancel when asked by the dialog box. The dependency section shows the artifact dependencies in both ways: it shows the list of arti- fact(s) the displayed artifact depends on but also the list of artifacts that depend upon the one you are browsing. 7.5.6 Artifact Cross-Referencing In addition to the rather formal way of expressing a dependency between two artifacts pre- sented in Section 7.5.5 [page 56], Codendi offers the ability to cross-reference any artifact, or 56
  • Codendi User Guide any other Codendi object from within a follow-up comment. When typing a follow-up comment, any text that follows the pattern "XXX #NNN" will be inter- preted as a reference to the artifact XXX number NNN, where NNN is the unique artifact ID, and XXX is the tracker short name (e.g. "bug #123", "task #321", "req #12", etc.). If you don't know the tracker short name or don't want to specify it, you may simply use "art #NNN". Each time Codendi displays a piece of text that follows this pattern it will auto-magically create an hyperlink to the web page showing all the details of the artifact. Codendi reference patterns may be used to reference artifacts, as well as source code commits, documents, files, etc. Please refer to Section 6.8.1 [page 30] for more details on Codendi refer- ences. Furthemore references concerning artifacts, svn revisions and cvs commits are stored in the database. They are displayed in the next section, ordered by type and initial reference direction. 7.5.7 Permissions on artifacts Tracker admins can restrict access to artifact. Those permissions are a complement to the per- missions defined at tracker level. The tracker admin just has to edit the artifact and update permissions like in the example below (where the artifact is currently restricted to project admins and members). Figure 19. Permissions d'un artefact 7.5.8 Artifact History The last part of the artifact update screen is devoted to the artifact history (see Figure 20 [page 58]). The artifact history keeps track of all the changes that occurred on all artifact fields since the creation of the artifact. 57
  • Codendi User Guide The artifact history shows what fields changed, what the old value was before the change took place, who changed it and when. Figure 20. Artifact History 7.6 Artifact Mass Change Codendi provides project and tracker administrators with the possibility to update several arti- facts in one step: delete/add the same CC name entry or file attachment to a set of artifacts, as- sign a list of artifacts to a person, etc... A typical application of the mass update feature is when a person leaves a project and all the artifacts that are assigned to her have to be re-affected to another person. 7.6.1 Selection Criteria The artifacts to be updated can be selected according to a set of criteria. These criteria are the same as for artifact browsing. For fine-grained control you may also select individually all arti- facts concerned by the mass change. Please see the Section 5.1 [page 21] for more detail on how to fill out the selection criteria. In the sample screen in Figure 21 [page 59] hitting the left button "Mass Change Selected Items" will select the three items checked individually, hitting the right button "Mass Change All Items" will select all nine items corresponding to the selection criteria. 58
  • Codendi User Guide Figure 21. Artifact Selection screen for the artifact mass change 7.6.2 Update Once you have selected all the artifacts to be updated you can now proceed to affect these changes via the Update screen. The Update screen for the Mass Change is very similar to the normal Artifact Update screen. It is divided into the following parts: Header, Comments, CC List, Artifact Attachments, and Dependencies. Figure 22. Header of Artifact Update screen for the artifact mass change 59
  • Codendi User Guide In the Header zone you find all the fields associated to the artifact. Only those that are changed from Unchanged to a defined value will be taken into account for the update. In our example in Figure 22 [page 59] only the "Assigned to" field of the three artifacts will be updated to a new value. All other fields remain unchanged. Figure 23. CC list of Artifact Update screen for the artifact mass change The CC List zone differs from the normal Artifact CC List zone in that it contains all the CC names of the selected artifacts with the information of in how many artifacts a CC name is used. If you add a CC Name it will be added to all the three artifacts. In our example in Figure 23 [page 60], there is one CC Name used in one of the three selected artifacts. By checking the "Delete?" box, the given CC Name will be deleted from this artifact. Equally, the Attachment zone contains any files attached to the selected artifacts with the infor- mation as to how many of those artifacts each file is attached to. The Dependencies zone is structured in the same manner. Each mass change is tracked in the project history (Section 6.13 [page 42]). On the other hand, no e-mail notification is sent in response to the mass change. 7.7 Artifact Duplication If artifact duplication is allowed for the tracker (see section Section 7.13.1 [page 68]), project members can duplicate an artifact. To duplicate an artifact, select an existing artifact (as though you want to update it) and click the "Copy this artifact" link. Then, you are in an artifact submis- sion screen, with all the values of the duplicated artifact. As summary must be unique, a copy information is just appended to the original summary. By default, a follow-up comment is pre- filled with an indication of the duplication, and a dependent is also pre-filled with a reference to the original artifact. Of course, you are free to modify the values of the duplicated artifact. Only project members are allowed to duplicate artifacts. 7.8 E-mail Notification The Codendi Tracker is equipped with a powerful and flexible e-mail notification system. Unless otherwise instructed by the project administrators or the users themselves, the e-mail notifica- tion system follows simple default rules. Whenever an artifact is created or updated - whether with an additional follow-up comment, a new attachment or a change in any of the artifact fields - an e-mail message is sent to the following actors: 60
  • Codendi User Guide • The artifact submitter (the person who initially submitted the artifact) • The artifact assignee (the project member to whom the artifact is currently assigned) • The people on the CC list if any (the persons who are listed in the CC list of a given arti- fact) • All users who posted at least one follow-up comment to the artifact. Beside these simple rules, the Administration module of the Codendi Tracker allows Codendi users to customize the email notification process. For further information see Section 7.13.10 [page 93]). The e-mail message generated by the Codendi Tracker first shows the most recent changes that occurred on the artifact in case of an update. It is then followed by a complete snapshot of the artifact. Web pointers are also included in the message to quickly and easily access the arti- fact form on Codendi. 7.9 Tracker Artifact Import Project Administrators have the means to import artifacts into Codendi trackers using the well known CSV (Comma Separated Value) format supported by all of the major office productivity suites. The artifact import functionality greatly facilitates the migration and integration of external project tracking and management tools into Codendi trackers. The import is divided into three steps: • CSV file submission. The project administrators can access the Import functionality from the tracker browsing screens or over the Project Administration Menu. Enter/ choose the tracker to update and specify the CSV file to import. In this step you can also check the option to send a mail notification to all users concerned by the artifact changes due to the import. If you don't check this option no notification will be sent. • CSV file parsing. If no parse errors were found in the uploaded file, a parse report is shown to validate that the information to import is correct. • Database update. Depending on the parsed information new artifacts are created or existing ones updated. 7.9.1 When to use the Import You will find below a couple of suggestions regarding the use of the tracker import feature: • Initial import from a project management software to your Codendi task tracker. • Migration of your legacy defect tracking system into your new Codendi defect tracker. • Migration of artifacts from one Codendi tracker to another. 7.9.2 Exporting Excel Sheets in CSV Format To export an Excel sheet to CSV format, simply follow the steps below: • Select File -> Save As • In the dialog window choose CSV as the Save as type 7.9.3 CSV File Parsing 61
  • Codendi User Guide The CSV format that is accepted as import input is accessible over the CSV file submission screen. This page allows manual validation of the tracker field labels, indicating which fields are mandatory in case of a new artifact submission. In addition, it gives you a sample CSV file. As for the export feature, you can specify the separator used in the CSV file you want to import as well as the date format (See Section 3.5 [page 16]). If you already use the Tracker Artifact Ex- port (see Section 6.11 [page 38]) you will notice that the format of the files to import and the ex- ported files are exactly the same. This means that if you changed your CSV separator for ex- porting data, you must use the same to import those data. You can refer to the export format es- pecially for the date formats as well as the format of the follow-up comments (see Section 7.5.2 [page 53]). The first record in the CSV import file is always the header row containing all the tracker field labels that will be used in the following artifact records. Depending on whether you want to import new artifacts or update the ones that already exist in the tracker you need to provide different information. Nevertheless, you can mix in one CSV file the submission of new artifacts and the update of existing ones. For the artifact creation you need to provide information on all fields that are specified as mandatory in the CSV import format except the Artifact ID which must not be specified. You may omit the submitter and submission date. The artifact submitter is then automatically set to the user importing the CSV file and the submission date will be the date of the import. For the artifact update you need to provide the artifact identifier of the artifacts to update. Beside this, you only need to provide the fields you want to update. All fields not specified in the CSV file will remain unchanged. The parsing method checks several potential errors in the CSV file: • Omission of mandatory fields when submitting new artifacts • Not the same number of columns in the header row and a artifact row • Unknown tracker field label • Field values that do not correspond to the predefined field values of a (multi) select box field • Double submission (i.e. submission of a new artifact with exactly the same summary as an existing artifact) • Unknown artifact identifier • Remove already submitted follow-up comments All other potential errors have to be checked manually by looking at the parse report table. 7.9.4 The Database Update If you import new artifacts, all non-mandatory fields that are omitted in the CSV file will be initial- ized to their default value. If you want to update the CC list or dependencies list of an existing artifact, be aware that the import will delete all former CC names or dependencies of the artifact and put the CC names or dependencies from the import file instead. All follow-up comments in the csv file that had al- ready been posted are removed to avoid double submission. The submitter and submission date of an existing artifact is never changed by an import even if the import file contains relevant information. If an error occurs for some artifact during the database update the following artifacts in the CSV file are not imported any more. 62
  • Codendi User Guide Each import is tracked in the project history (Section 6.13 [page 42]). On the other hand, no e- mail notification is sent in response to the import. Tip: Excel and Regionals If a .csv file is opened in Excel, any change to the spreadsheet (even something as simple as a col- umn resizing) may cause Excel to modify and update the .csv file. Changes that may occur include: dates, times and numbers converted to the same format as those used by your system's regional settings, single line feeds converted to line feed and carriage return, extra commas appended to cer- tain lines. The updated date format might not be compatible with the Codendi date format and potentially cause troubles when importing such updated CSV files back into Codendi. On the other hand Codendi-ex- ported CSV files might not open correctly under Excel in certain Regionals. If you have a .csv file that either will not open correctly under Excel or was opened in Excel and will not import into Codendi please try the following: Make sure all applications are closed. Change your system's regional settings (Start > Settings > Control Panel > Regional Options) to use the English with the following formats: Date = MM/dd/YYYY Time = hh:mm. Using Excel, open the .csv files that don't import, make a column width change, save the files and exit Excel. Go back and restore your original regional settings. Import the "fixed" .csv file into Codendi. 7.10 Default Tracker Access Permissions Depending on the class of citizen a user belongs to and the level of permissions granted as a project member, the various features of the Codendi Tracker may or may not be accessible. Please note that the default access permissions listed below may change for a particular tracker if the tracker administrator modifies the access permission settings. For more information on how to configure tracker access permissions see Section 7.13.2 [page 69]. Default permission settings are summarized in the table below: Tracker Feature Access Permission New Artifact Submission By default any Codendi visitor, whether logged in or not, has the ability to submit a new artifact to a tracker. The tracker administrator has the ability to limit the scope of this feature to Codendi registered users (anonymous users are requested to login first) or to the project members if the tracker is made private. Artifact Browsing Searching the Artifact database and browsing the results is available to all Codendi visitors (whether registered or not) unless the tracker has been made private by the project ad- ministrator. If so the tracker is only visible to project mem- bers. Artifact Update By default only project members can update an artifact. Non members have only limited access and can only add a com- ment or attach a file. Mass Update of Artifacts Only available to project administrators and project members with Admin. and Tech. permission on this tracker. Tracker Artifact Import Only available to project administrators and project members with Admin. and Tech. permission on this tracker. Tracker Creation Only available to project administrators. Tracker Administration - General Settings Only available to project administrators and project members with Admin. permission on this tracker. Tracker Administration - Field Usage Manage- Only available to project administrators and project members ment with Admin. permission on this tracker. Tracker Administration - Field Values Manage- Only available to project administrators and project members 63
  • Codendi User Guide Tracker Feature Access Permission ment with Admin. permission on this tracker. Tracker Administration - Reports Management Only Project administrators and project members with Admin. permission can define project wide tracker reports that will be available to all users. All other Codendi users (except anony- mous users) can define personal tracker reports. Tracker Administration - Email Notification Set- Only Project administrators can add email addresses in the tings global email notification field. Project members can watch ar- tifacts of other team members. Any registered Codendi user can customize her notification preferences. Table 1. Default Tracker Access Permissions 7.11 Tracker Creation Before one can define what fields and field values to use in a tracker it must first be created. Tracker creation can be accessed from the "Create a New Tracker" menu item that is available either in the public part of the tracker or in the Tracker Administration section. Tip: Use the predefined trackers first! When a new project is created on Codendi a number of trackers are automatically created for this project. This would typically be a bug tracker, a task tracker and a support request tracker. If your project manages this type of artifact please use the predefined trackers first. Of course, you are free to define new fields or customize existing ones in each of the trackers. To define a new tracker you must provide the following information (see Figure 24 [page 65]): • Name: this is the name of your tracker. A tracker is typically named after the type of arti- fact it is going to manage. This name will be used by Codendi in the title of the various screens of the trackers. Typical examples of tracker names are: Action Requests, Sup- port Requests, Requirements, Defects, Bugs… • Description: A longer description of what this tracker is all about and the type of man- aged artifacts. • Short name: this is a short name that best describe the type of artifact managed in this tracker. This name must be quite short as it is used in various screens of the Codendi Tracker like the artifact update form where it appears in the tracker menu and also next to the artifact ID. Following the examples given for the Name field above, short names can be: AR for Action Request, SR for Support Requests, Reqt for Requirements, bug for Bugs… 64
  • Codendi User Guide Figure 24. Creation of a new tracker (here a defect tracking system) The next step is to decide upon the set of fields available for this tracker. In order to avoid the pain of defining the most common type of trackers again and again (e.g. Bug tracker, Support Request tracker, etc.) Codendi offers the ability to create a new tracker from a set of templates. Those templates are either Codendi-wide templates (also known as site templates) or project specific templates. Remark: using a template doesn't mean you have to stick to the list of fields and field values de- fined in this template. You can always add or remove fields or fine-tune the field settings after- wards. • Codendi-wide Template: these are templates that have been defined by the adminis- trators of the Codendi site because it is expected that most project needs them. It is also a way to ensure a certain level of harmonization across projects that will make develop- ers' life easier. The list of available templates may vary from one Codendi site to another but you will typically find templates for Bugs, Tasks, etc. A specific tracker called "Empty" allows you to create a virgin tracker with no predefined fields other than the minimal set of required fields. See Section 7.12 [page 65] for more explanations on the semantic of those templates. • Project Templates: in case you have already defined a tracker that suits your needs or you have seen a tracker from another project that you'd like to reuse, you just have to specify the project ID and tracker ID either by hand or from the pull down menus and click on the create button to create the exact same tracker in your project (Note: this does not copy the artifacts of the original tracker but only the field settings). 7.12 Codendi-wide Tracker Templates The standard trackers provided for each new Codendi project are: • Bugs 65
  • Codendi User Guide • Patch • Support Requests • Tasks • Scrum Backlog Each of those templates have predefined fields that correspond to the specific work processes around bugs, patches etc. In the following, we give a short overview of these different work pro- cesses. For each of those templates, the Codendi Team also tried to maintain a fair balance be- tween sophistication and ease of use. As a consequence, fairly simple and straightforward tem- plates are configured by default for all new hosted projects. Then it is up to the project members to decide how much information they want to see attached to an artifact and customize their tracker configuration accordingly. 7.12.1 The Bug Tracker Template One of the golden rules in a collaborative project environment is to let your project community test the software and freely report on any defect (or bug) they have seen. The Bug template was developed with this objective in mind. The template Bug Tracker comes pre-configured with a set of fields (used or not) that are proba- bly enough for the majority of projects hosted on Codendi. You can either decide that the tem- plate is lacking some critical fields that you can create or, on the contrary, switch some fields to the "Unused" status to make the tracker simpler. 7.12.2 The Patch Tracker Template The role of the Patch tracker is to let non project members or project members with restricted permissions to contribute source code modifications to the project. On how to generate source code patches see the CVS chapter (Section 9.4.6 [page 117]) or the Subversion chapter (Section 10.5.7 [page 134]). A note to the project team Receiving source code modifications or other contributions from other Codendi users does not imply that you have to accept the new code and insert it in your main source tree. It is up to the project team to decide what to do with it. One of the interesting features of the Patch tracker is that submitted patches are available to anybody at all time regardless of the final decision of the project team. Therefore any Codendi visitor is free to download any submitted patch and apply it onto its own version of the software even if the project team has decided not to apply the patch on the main source tree. 7.12.3 The Support Request Tracker Template The Support Request (SR) tracker is one of the communication mechanisms that your project should offer to the project community. It allows any Codendi user to ask question to the project team and call for assistance. Codendi users who have access to the tracker can follow the thread of discussions between the other users and the project team. It is also possible to review all the SRs that were posted in the past and the answer given by the project team. With the Support Request tracker, a project team can easily and efficiently coordinate technical support activities. 66
  • Codendi User Guide 7.12.4 The Task Tracker Template The Codendi Task tracker is a task manager and not a project management software like CA- SuperProject, MS-Project or other powerful and complex desktop products available on the mar- ket. The Codendi Task Tracker cannot build a Pert chart, it doesn't have any planning capabili- ties. It is rather a time sheet tool which allows project members to track their time and manage other things like weekly TODO list for instance. However the Codendi Task Tracker offer a number of features that makes it very complemen- tary with the above mentioned project planning tools: • Like all Codendi tools, the Task Tracker is entirely web based. Therefore any project member can update his/her time sheet regardless of its physical location. • Tasks can be managed by authorized project members. • Each project member has its own time sheet showing all open tasks assigned to her, their priority, description, start and end dates, percentage completion, related tasks, fol- low-up comments and a full audit trail of the past changes. • Task data can be collected by the project leader(s) at any point in time and exported out of the Codendi project thanks to the Project Data Export facility (see Section 6.11 [page 38]). This allows for an easy generation of progress reports or project re-planning. 7.12.5 The Scrum Backlog Template Codendi makes it easy to implement the Scrum methodology, by providing a Scrum Backlog tracker to each project. You will find a comprehensive description of Scrum on Wikipedia. The Scrum Backlog tracker contains artifacts called "User Stories", that describe needs ex- pressed by the customers of the project. The tracker has been customized to capture customer requirements: it is possible to define the customer value of each story, its acceptance criteria, its effort, its current backlog (Product Backlog or Sprint Backlog), etc. Other optional fields are available, and of course, each project may customize the tracker to fit the way it implements the methodology At the beginning of a Scrum project, each customer user story must be stored in the Product Backlog ('Backlog' field of the tracker). During the first Sprint Meeting, a few stories are selected by the team to be implemented in the first iteration. They are moved to the "Sprint Backlog" ('Backlog' field), and evaluated ('Initial Effort'), or even duplicated into smaller stories. The team then affects the stories to team members ('Owner') and can start developing. At the end of the Sprint (after two to four weeks), the team meets for the new Sprint Meeting. User stories selected in the past Sprint are updated, and new stories are selected for the next Sprint. 7.13 Tracker Administration As we went through the description of the Codendi Tracker features, we referred several times to the flexibility of this system and how easy it is to customize your own tracker. This can be done through the Tracker Administration module available under the "All Trackers Admin" menu item in the Tracker Menu bar. 67
  • Codendi User Guide The top level administration screen shows a list of existing trackers for your project. From this page, existing trackers can be configured and new ones can be created (see Figure 25 [page 68]). This section focuses on the configuration of an existing tracker. Creation of new tracker is covered in Section 7.11 [page 64]. Figure 25. Tracker Administration - Top Level Page The configuration settings for a given tracker is divided in seven sections: • General Settings: name, description and some other general purpose parameters are defined in this section. • Permissions Management: allows you to give different access permissions to different users depending on their role. • Manage Field Sets : this is where you'll decide what field sets to use in your tracker. • Manage Field Usage: this is where you'll decide what fields to use in your tracker. • Manage Field Values: this section allows you to define the lists of values to be used by certain fields. • Manage Canned Responses: allows you to create some pre-defined follow-up com- ments that your team is using on a regular basis. • Manage Reports: search and browsing templates for the artifact search screen are de- fined here (search criteria et results table). • Email Notification Settings: fine tuning of the global and personal email notification settings. 7.13.1 General Configuration Settings This module allows you to define a series of properties for your tracker. Some of those proper- ties have already been defined in the tracker creation form while some others are only available on this configuration page. The properties are as follows: • Name: this is the name of your tracker. More precisely you want to name your tracker after the type of artifact that are going to be managed in your tracker. This name will be used by Codendi in the title of the various screens of the trackers. Typical example of tracker names are: Action Requests, Support Requests, Requirements, Defects or Bugs… • Description: A longer description of what this tracker is all about and the type of artifact that it manages. 68
  • Codendi User Guide • Short name: this is a short name that best describe the type of artifact managed in this tracker. This name must be quite short as it is used in various screens of the Codendi Tracker like the artifact update form next to the artifact ID. Following the examples given for the Name field above, short names can be: AR for Action Request, SR for Support Requests, Reqt for Requirements, bug for Bugs… • Allow artifact duplication: if artifact duplication is allowed or not. If it is, only project members are able to duplicate artifacts. • Instantiate for new projects: This parameter is only displayed when working on a "tem- plate" type of project (see Section 6.5 [page 27]). If the parameter is selected, then projects created from this template project will have this tracker created. If not selected, the tracker will not be available in the new project. • Submit instructions: an introductory message that displays at the top of the artifact submission form. This is a convenient way to give directions and recommendations to the submitter. The text must use HTML tags for formatting which gives a great flexibility to shape the content of this preamble (you can use bold, italic, colors, embedded URL…) • Browse instructions: an introductory message that displays at the top of the artifact searching and browsing screen. The text must use HTML tags for formatting which gives a great flexibility to shape the content of this preamble (you can use bold, italic, colors, embedded URL…) 7.13.2 Permissions Management This module is used to give different access permissions to different users depending on their role. Access permissions to a tracker can be defined at two levels: • Tracker/Artifact level: at this level, you can define the group of users who have access to only certain artifacts or have no access at all. • Field level: this is a more fine-grained level, where access permissions can be defined field by field. Using this feature you can specify which groups has read-only permission on a field, which ones can modify it or which ones do not have access to it at all. All access permissions are defined for groups of users rather than individuals. See Section 6.10 [page 35] for more information on how project administrators can define and manage groups of users. Tracker and Artifacts Permissions Management When entering this module, a list of user groups appears along with their access permissions. The user group list first shows groups of users defined at the system level like all_users, regis- tered_users, project_members, etc. These are groups that Codendi manages for you so you don't have to keep them up to date when new users subscribe to the site or become member of your project. The second part of the user group list shows all groups of users defined at the project level (see Section 6.10 [page 35] for more information on how to define and manage groups of users). Each group can be associated with the following access permissions: • -: this level of permission that displays as a hyphen means that the group has no spe- cific permission. • access to all artifacts: when granted this permission a user group has access to all the 69
  • Codendi User Guide artifacts of the tracker. • access to artifacts assigned to group: when granted this permission a group of users can only see those artifacts that have been assigned to one or several members of this group. • access to artifacts submitted by group: when granted this permission a group of users can only see those artifacts that have been submitted by one or several members of this group. • access to artifacts assigned to or submitted by group: when granted this permission a group of users can only see those artifacts that have been submitted by or assigned to one or several members of this group. Example: Using tracker access permissions with your clients Figure 26. A sample tracker permissions screen As an example of how you can use these permissions let's assume that you have created a tracker where several of your customers can report defects on your software. In such a situation, you may decide that a customer from a given company should only see those defects that were submitted by its employees and not those submitted by other companies. To achieve this you just need to create a group called 'company_A' in which you include the login names of all the users working for company A. Then do the same with the group 'company_B' for company B. Those two groups will then be given the 'access to artifacts submitted by group' type of permission. In addition you probably want to grant 'access to all artifacts' to the project members or to the 'tracker_administrators' groups so that your team members can manage artifacts from any customer. In this example: • a user which is not logged-in will not have access to artifacts, • a user which is logged-in will not have access to artifacts, • a project member will have access to all artifacts, • a project admin will have access to all artifacts, since a project admin is a project member, • a tracker admin will have access to all artifacts, since a tracker admin is a project member, • a member of ugroup Company_A will only have access to artifacts submitted by members of the ugroup Company_A (the same for Company_B), • a project member which is also member of ugroup Company_A will have access to all artifacts since he is a project member, • a member of ugroup Company_C will not have access to artifacts (if he is not also member of a ugroup like project_member, Company_A or Company_B). 70
  • Codendi User Guide Field Permissions Management Beside defining access permissions for the tracker and its artifacts (see Section [page 69]) it is sometimes necessary to restrict access to certain fields of the tracker to a given population. As an example if you share a defect tracking system with your customers you may want to hide some fields from the view of your customer or prevent them from modifying certain fields. This is precisely what this module is meant for. When using this configuration module, you can toggle the display between two different views: you can either view all user groups permissions for a given field OR for a given user group you can view all the field permissions defined for it. The experience shows that the view by field is often the preferred one when you configure a tracker for the first time whereas the view by group of users is more convenient to adjust the permission settings later on (see Section 6.10 [page 35] for more information on how to define and manage groups of users). Each group of users can be granted the following permissions for a given field: • Can submit: this permission determines whether a group of users can define the initial value of a field when an artifact is first submitted. If not checked, this field will not be vis- ible on the submission screen for this user group. • Read-only: if granted read-only permission a group of users only has read access to a field. In other words the users see the value of the field but cannot modify it. • Update: if granted update permission, a group of users can see the current value of a field and also modify it. • -: this level of permission that displays as a hyphen means that the group has no spe- cific permission, like in tracker permissions. Important Note: the permissions associated with a field apply in many areas of a tracker. For instance if a group of users has no access to a given field, this field becomes invisible on the ini- tial submission form, on the artifact search form as well as in the table of results returned by the search, in the artifact update form, in the history of changes associated with each artifact and fi- nally in the email notification sent to this group of users. 7.13.3 Field Sets Management In order to improve the input of the artifact submission form, the fields of the trackers are grouped in field sets. This allows to open up the submission form, or to clusterize fields that have same semantics, or also to group fields that play a particular part (for instance, you could clusterize fields aimed to be filled by the one who is responsible for the diagnosis of the artifact, and then group fields aimed to be filled by the one who is in charge of fixing it, etc.). Each field must belong to a field set, and a single field can only belong to only one field set. Tracker Field Set List To manage the field sets for this tracker, select the item "Manage field sets" on the welcome page of any Tracker Administration screen. The Field Set screen (Figure 27 [page 72]) shows you a sample list of field sets available in the tracker of a Codendi project. The screen is divided in 2 parts: 1. the list of tracker field sets currently in use 2. a form to create new tracker field sets. 71
  • Codendi User Guide Information displayed on the Tracker Field Set list page are as follows: • Field Set Label: the name of the field. To change the properties of a field set simply click on the field set name. • Description: the field set description • Fields belonging to this field set: list of the fields that belong to this field set. The used fields are displayed in bold, the unused ones in italic. • Rank on screen: the rank number indicates in which order the field sets will appear on the artifact submission form and the artifact update form. Field sets with a smaller rank number are displayed first. • Delete?: when a field set is deleted, it completely disappears from the list of available field sets. Only empty field sets (that means not including any field) can be deleted. 72
  • Codendi User Guide Figure 27. Field Set screen of a project tracker Creation and Modification of a Tracker Field Set The forms used for the creation of a new tracker field set or the modification of an existing one being very similar both are covered in the same section. The field set creation form is available at the bottom of the tracker field set list where as the field set update form can be accessed by clicking on the field set label located on the left hand side of the field set list. Properties that can be tuned for a tracker field set are as follows: • Field Set Label: this is the name of the field set. • Description: a longer description of the purpose of this field set. • Rank on screen: this arbitrary number allows you to define the position of this field set on the artifact submission form and the artifact update form relative to other field sets. The field sets with smaller values will appear first on the screen. The rank values doesn't have to be consecutive values. It is a good idea to use values like 10,20,30,... so that it is easy for you to insert new field sets in the future without having to renumber all the field sets. 7.13.4 Field Usage Management When a tracker is first created, it comes pre-configured with a set of fields inherited form the template that was used to create it. For the majority of projects hosted on Codendi it is very likely that the standard Tracker templates (e.g Bugs, Tasks, Support Requests) will cover most of the needs. However Codendi gives you the ability to customize the list of fields for your trackers. It can be a variation on an existing template with some field addition or removal or it can be an entirely new tracker created from an empty template. Tracker Field Types The fields of a tracker can be of several types: Select Box, Multi-Select Box, Text Area, Text Field, Integer Field, Float Field and Date Field. Find below a detailed description of each type: • Select Box: a "Select Box" field takes its value from a predefined list of values defined by the tracker administrator. Depending on the browser you use it may be displayed slightly differently but it is generally shown as a pull-down menu with the list of prede- fined values. At any given time this type of field can only be assigned one single value. • Multi-Select Box: like the Select Box field described above this field takes its value from a predefined list of values. As opposed to the Select Box field, the Multi-Select Box can be given multiple values at once by the end user. As an example, this type of field can be used to assign several persons to a given task in a task tracker. • Text Area: allows the user to enter free text in a multi-line text area. The field "Original Submission" that is used to describe in details a defect, a task, etc. is of type "Text 73
  • Codendi User Guide Area". • Text Field: allows the user to enter free text either in a one-line text field. The summary of a defect or a task is a good example of a one-line text field. • Date Field: one-line field that only accept ISO formatted dates (YYYY-MM-DD) • Integer Field: one-line field that only accept well-formed integral numbers (e.g 3, -100, 2345…) • Float Field: one-line field that only accept well-formed floating point numbers (e.g 3.56, - 100.3, 2345, 34E+6…) Tracker Field List To decide what field to use and what field not to use select the item "Manage Field Usage" on the welcome page of any Tracker Administration screen. The Field Usage screen (Figure 28 [page 75]) shows you a sample list of fields available in the tracker of a Codendi project. The screen is divided in 3 parts: 1. the list of tracker fields currently in use 2. the list of unused tracker fields (not shown on Figure 28 [page 75]) 3. a form to create new tracker fields (not shown on Figure 28 [page 75]) Information displayed on the Tracker Field list page are as follows: • Field Label: the name of the field. To change the properties of a field simply click on the field name. • Type: tracker fields can be of several types: Select Box, Multi-Select Box, Text Field, Text Area, Date Field, Integer Field or Float Field. For a detailed description of the field types see Tracker Field Types. • Description: the field description. • Field Set : field set the field will belong to. • Rank on Screen: the rank number indicates in which order the fields will appear on the artifact submission form and the artifact update form. Fields with a smaller rank number are displayed first. The rank numbers are relatives regarding the field sets. This means that the fields are first displayed by field sets, and then by rank number, inside their own field set. • Status: • Used: the field is used by the tracker. • Unused: the field is not used by your tracker. Note that an unused field is just a "hid- den" field. if you change the status of a field from used to unused all the data associ- ated with this field are preserved. • Delete?: when a field is deleted, it completely disappears from the list of available fields. Furthermore all the data associated with this field is destroyed from all artifacts. 74
  • Codendi User Guide Figure 28. Field Usage screen of a project tracker Creation and Modification of a Tracker Field The forms used for the creation of a new tracker field or the modification of an existing one be- ing very similar both are covered in the same section. The field creation form is available at the bottom of the tracker field list where as the field update form can be accessed by clicking on the field label located on the left hand side of the field list. Tip: Use Predefined Fields First! At any time in the life of your project you can enrich your trackers with new custom fields. However before you decide to create a new field make sure that there isn't a predefined field that already plays the same role. By using predefined fields whenever possible, you'll contribute to keep the global Co- dendi environment consistent and make it easier for visitors, contributors or new team members to switch from project to another. Properties that can be tuned for a tracker field are as follows: • Field Label: this is the name of the field. Although you are entirely free to change the name of a field, we recommend that you only change it for a new name with a similar meaning. If you want to change the name for something radically different then we rec- ommend that you create an entirely new field and you leave the existing field in the list of unused fields. • Description: a longer description of the purpose of this field. 75
  • Codendi User Guide • Field Type:tracker fields can be of several types: Select Box, Multi-Select Box, Text Area, Text Field, Integer Field, Float Field and Date Field. For a detailed description of the various field types see Tracker Field Types • Display Size: this property allows you to define how much space a field is going to take on the screen. It has a different meaning and a different format depending on the field type. • Select Box: the display size does not apply to a select box. Any input typed in the display size field will be silently ignored. • Multi-Select Box: the display size is made of a single number which indicates how many of the values associated with this field are visible at once. A reasonable value for the size of multi-select box is between 2 and 5. • Text Field, Integer Field, Float Field: for all one-line fields, the display size follows the pattern "V/M" where V is the number of character visible at once in the field dis- play window and M is the maximum number of characters that can be typed for this field. If V is less than M then the text will shift in the visible window as more text is entered. The maximum value of M is 255. A display size of "10/40" means a field that accepts 40 characters maximum and the field display is 10 characters in width. • Date Field: A date always follows the same pattern (YYYY-MM-DD) and therefore it always has a fixed length of 10 characters. • Text Area: for text areas, the display size follows the pattern "C/R" where C is the number of columns in the text area (the width in number of characters) and R is the number of rows or lines of text. Note that the number of lines is not limited to R. If the text typed in the field has more than R lines then a scrollbar will show up to navigate through the text. A display size of 60/7 means a text area with 7 lines that are 60 characters long. • Field Set : it is the field set the field will belong to. Each field must belong to a field set, and a field cannot belong to more than one field set (in other words, a field belong to one and only one field set). • Rank on screen: this arbitrary number allows you to define the position of this field on the artifact submission form and the artifact update form relative to other fields. The fields with smaller values will appear first on the screen. The rank values doesn't have to be consecutive values. It is a good idea to use values like 10,20,30,... so that it is easy for you to insert new fields in the future without having to renumber all the fields. • 76
  • Codendi User Guide Figure 29. Tracker field usage settings • Allow Empty Value: determines whether leaving the field blank in the artifact submis- sion or update form is allowed or not. If unchecked the tracker won't accept the form un- less the field is given a value. The fields that must be filled out are marked with a red start on the submission and modification forms. • Keep Change History: determines whether changes made to this field will be kept in the artifact history (see Section 7.5.8 [page 57] ) • Use this field: This checkbox only appears on the field usage modification screen. When first created a field is automatically given the status "Used" (checkbox marked). Fields becoming unused will simply be hidden from the user view but all data attached to this field in the artifact database remains untouched. In other words, returning a field from unused to used will also restore the field data as they were before. Only the actual deletion of a field destroys the field data (see Section [page 74]. 7.13.5 Field Values Management Once fields have been defined for your tracker, the next step is to define a set of values for your fields. This mostly applies to "Select Box" and "Multi-Select Box" type of fields where the list of values you are going to choose will show up in the pull-down menus when an artifact is submit- ted or updated. Other field types are simply one-line fields with no restricted set of values. For those fields only the default value can be defined. Field List 77
  • Codendi User Guide To configure values assigned to the used fields of your tracker select the item "Manage Field Values" on the welcome page of the Tracker Administration screen or select the "Manage Field Values" item from the Tracker Administration menu bar at the top of the screen. Figure 30. Tracker field list with user definable values Information displayed on this page are as follows: • Field Label: the name of the field. Click on this name to view the list of values for this field. • Description: what this field is about Browsing Tracker Field Values A click on any of the fields listed in the Field Value Management screen (see Section 7.13.5 [page 77]) brings you to the list of existing values for this field (see Figure 31 [page 79]). The table of values shows the following information: • Value Label: text label of the value as shown in the select box. Click on this label to modify the value settings (see Section [page 80]) • Description: meaning of the value • Rank: defines the order of the field values in the select box. The smaller values appear first at the top of the select box. • Status: • Active: the value is currently visible in the pull-down menus and can be assigned to the corresponding artifact field. • Hidden: the value is currently not visible in the pull-down menu. However if this value was used in the past by any of your project artifacts, it will continue to show up OK for this specific bug. • Permanent: this value has been defined for all trackers using the associated field it cannot be hidden nor deleted. Only the site administrators who have acces to the site tracker templates can mark values as permanent. The Figure 31 [page 79] shows the list of available values for the Resolution field of tracker man- aging "Bugs" artifacts. The Resolution field comes with set of predefined values that are avail- able to all Codendi projects. By default 8 values are active (Accepted, Analyzed, etc.). 78
  • Codendi User Guide Of course you are free to add your own values to the Resolution field. However, in order to keep a certain harmony from one Codendi tracker to another, we highly recommend that you use the list of predefined resolution values as much as you can before creating new ones. Figure 31. List of values for the "Resolution" field Defining a Default Field Value All fields used in a tracker can be assigned a default value. Depending on the field type you will be presented with either a free text field for text, date, integer and float fields or a select box containing all the values already defined for this field for select box and multi-select box fields (not shown on Figure 30 [page 78]) . Creating a Tracker Field Value To add a value use the value creation form located below the list of field values (not shown on Figure 30 [page 78]). Binding a Field to a List of Values Not only does the Codendi Tracker allow you to create a list of values for a select box but it also offers the ability to associate a select box with a list of predefined values that is actually dynami- cally generated by the Codendi system. A typical example of this is when one would like to cre- ate a new select box showing the list of project members. Instead of creating and maintaining the list of values manually, Codendi builds this list for you and allows you to bind it to a field of type select box. Note that if you decide to bind a select box to a list of dynamically generated values you can no longer create your own values. The following lists are currently available (others may be added in the future): • Project Members : list of people belonging to the project. • Project Administrators : project members who have been granted the status of project administrators. • Artifact Submitters: the full list of people who once submitted an artifact to the tracker. • Project Defined User Groups: you can bind a select box to any of the user groups that are defined by the project. To see how to define such user groups refer to Section 6.10 [page 35]. 79
  • Codendi User Guide Updating a Tracker Field Value From the screen showing the list of values for a given field (see Figure 30 [page 78]) you can change the properties of a field value by clicking on the value label: • Value: change the value itself. The value typed here will appear as is in the pull-down menu. Keep in mind that if you change a value, the change will also reflect in the arti- facts that were using the old value. • Rank: a number that allows you to specify where you want this value to appear in the list of all active values. The values with smaller rank are displayed first. When the "None" value is available for this bug field it has a rank number of 10. This number is deliberately small because by convention "None" always appear at the top of the pull- down menu. Please be a good Codendi citizen and choose rank numbers higher than 10 for your own values. • Status: Active or Hidden. As explained above going from one to the other in the course of the project life has no negative impact on the artifact database. • Description: says a bit more about the meaning of this value. Figure 32. Setting a field value Tip: Leave some space between rank numbers Whether for Fields or Field Values remember to use large numbers (in the hundreds or the thou- sands like 100, 200, 300,..) when you create new values. By doing so you'll make your life easier if you ever want to insert new values in between existing ones in the future and avoid a tedious renum- bering of the existing items. 7.13.6 Field Dependencies Field dependencies allow us to link source field values to target field values. In other words, the values proposed to a final user for a field will depend upon the value selected for another field. As an example, if you define a field Operating System(Linux, MacOS X, MS Windows, NetBSD) and a field Version(2.0, 2.1, 2.2, 2.4, 2.6, 3.0, 10.1, 10.2, 10.3, 10.4 (Tiger), NT, 2000, XP), you can define dependencies in the tracker administration interface: 1. First, select the source field "Operating System" then the target field "Version". All val- ues for both fields are displayed. Values which are part of a dependency between the 80
  • Codendi User Guide two field are emphasized (in bold). 2. To create dependencies between Linux and the corresponding versions, you just have to select the source value and check/uncheck corresponding values in the target field. The highlighting helps to link source and target values, with the small arrows indicating the direction of reading, "source to target". 3. You can cancel your modifications by clicking on the reset button. Once validated, the modifications are saved. Here are the dependencies for Linux: Figure 33. Linux Dependencies Now you can continue with the next source value MacOS X: 81
  • Codendi User Guide Figure 34. MacOS X Dependencies Thus, with the next source value MS Windows: 82
  • Codendi User Guide Figure 35. MS Windows Dependencies And, with the last source value NetBSD: 83
  • Codendi User Guide Figure 36. NetBSD Dependencies We>You can also "navigate" through dependencies in the opposite direction: to define the source values which influence one target value: 84
  • Codendi User Guide Figure 37. Version 2.0 depends upon Linux and NetBSD systems Once dependencies are defined, the final user (when submitting/updating an artifact) will see the Version options filtered according to the selection of the Operating System: Figure 38. Proposed versions for Linux 85
  • Codendi User Guide Figure 39. Proposed versions for MacOS X Figure 40. Proposed versions for MS Windows Figure 41. Proposed versions for NetBSD When you define your dependencies, please be aware of the following points: • Only Select Boxes and Multi Select Boxes can have dependencies, • The cyclic dependencies are forbidden (Field 1 => Field 2 => ... => Field 1), • A field can depend upon only one field, • Javascript must be allowed on the browser to manage dependencies, • If a field is not the target of a dependency, then it will propose all its values. On the op- posite, it will propose only those which satisfy the dependencies. 7.13.7 Canned Responses 86
  • Codendi User Guide One frequently sees project members in charge of the artifact classification and dispatch pro- cess posting the same follow-up comments repeatedly. Typical examples of repeated posted comments are: a thank you message to the originator, a request for the originator to provide commonly missing information like version numbers or type of machine used, etc. (see Figure 42 [page 87] Rather than repeatedly typing the same follow-up comments, Codendi allows project members to create a predefined set of responses. After these canned responses have been defined, post- ing a follow-up comment is just a matter of selecting the appropriate response from the pull down menu in the artifact update form. Also note that defining a new Canned Response can be done on the fly from the artifact update form by clicking on the "define a new Canned Response" link (see Figure 17 [page 54]). Figure 42. Definition of Canned Responses 7.13.8 Tracker Report Management Knowing that project administrators, project members and other Codendi users may have differ- ent needs in searching the tracker database, Codendi offers the ability to define project or user specific tracker reports. Creating a tracker report consists in deciding what fields you want to use as search criteria and what fields you want to see in the columns of the table where the results of the search are pre- sented. You can also define the order in which the search criteria and the columns will appear on the screen. Tracker Administrators have the ability to define tracker reports that will be usable by all regis- 87
  • Codendi User Guide tered users who have access to the tracker whereas all other users can only define reports for their personal use. Tip: Tracker Reports specifies the report layout not the report content While configuring Tracker reports you will probably notice that the configuration screen allows you to define the fields that you are going to use a search criteria but not the values of this search criteria. This is on purpose. Defining a report template and filling out the search template with content (values) are 2 distinct operations on Codendi. Once a report template has been defined in the admin- istration module (e.g 'Simple Report', 'QA report', 'Daily report' ...) you can go to the tracker searching and browsing module and use the report template for all sorts of queries. Select the report you want from the pull-down menu, fill out the search form with the values you are interested in and click on the browse button. Then you can save the entire query (report plus values) with the Codendi book- marking mechanism (see tip in Section 7.4.1 [page 47]). And voila! Browsing Tracker Reports Clicking on the "Manage Reports" item in the Tracker Administration menu bar at the top of the page displays the list of available reports (see Figure 43 [page 88]) with the following information: • ID: a number that uniquely identify the report. A click on the report ID brings you to the report configuration screen (see Section [page 89]). • Report Name: the report short name as it will appear in the report select box when you'll be using the artifact browsing screen (e.g. Simple Report, QA report, Monthly Re- port…). • Description: a longer description of the report. • Scope: • Project: this report will be usable by all project members. Only tracker administrators can define project-wide reports. • Personal: this report will be usable by its creator only. • System: this report is defined at the system level and cannot be removed. The de- fault tracker report that comes pre-configured with each tracker is a system report. • Delete?: click the trash icon to delete the report. Project-wide reports can only be deleted by project administrators. Figure 43. Example of a list of tracker reports The same interface is available to browse the trackers graphical reports. 88
  • Codendi User Guide Tracker Report Setting After you click on a report ID in the report list (see Section [page 88], the report setting screen appears (see Figure 44 [page 90]). This screen allows you to define what fields you'd like to use as search criteria and what fields you'd like to see in the list of artifacts retrieved from the database. Information available on this screen are as follows: • Name: each report must be given a name. This name must not be too long as it will ap- pear in a select box in the artifact browsing module when you are asked to choose what tracker report you want to use to query your artifact database. • Scope: tracker administrators can define project-wide reports that will be made avail- able to all users. Non tracker administrators can only define personal report. • Description: a longer description of the report. • Field selection: the field table shows all the fields that are currently in use in your tracker. For each field you can set up the following parameters: • Use as a Search Criteria: If you check this box the field will appear as one of the se- lection criteria when you search the tracker database. • Rank on Search: A number can be entered in this field. The rank number allows you to place the field with respect to the others. The fields with smaller values will appear first on the list of selection criteria displayed on the screen. These number doesn't have to be consecutive numbers. • Use as a Report Column: If you check this box the field will appear as one of the col- umn in the search results table. • Rank on Report: A number can be entered in this field. The rank number allows you to place the field with respect to the others. The fields with smaller values will appear first in the search results table (from left to right). These number doesn't have to be consecutive numbers. • Column Width(optional): In case you want to impose a specific width to the column in the report table you can specify a column width in percentage of the total page width. This is optional and our recommendation is to leave it blank unless your Web browser doesn't make a good job at formatting your table. If you want a column to be as narrow as possible while preserving word boundaries enter a very small percentage like 1 or 2 in the column width field. Note: it is perfectly OK to use a field as a search criteria and not as a column in the tracker re- port and vice versa. For the fields you don't want to use at all in the report leave both check boxes. 89
  • Codendi User Guide Figure 44. Setting a Tracker Report 7.13.9 Tracker Graphical Report Setting After you click on a graphical report ID in the graphical report list (see Section [page 88]), the re- port setting screen appears. This screen allows you to define what type of graphs will be dis- played . There is three graph types supported: Pie, Bar and Gantt. Creating / Editing a graph To create a new graph for the graphical report, juste click on the type of the graph you want to create, Pie, Bar or Gantt. To edit an existing graph, click on the pencil button in the upper right corner of the graph. By clicking on the red cross buton, you will delete the graph. Commun infor- mations available on the creation /edition screen available are as follows: • Title: each graph must be given a name. This name must not be too long as it will ap- pear in the upper center of the graph. • Description: enter a short description of the graph here, it will appear under the title in the graph. • Rank: the rank sets the display order of the varioux graphs in the graphical report. Creating / Editing a Pie graph Specific informations available for the Pie graph are as follows: • Width and Height: set the size of the graph in pixels. • Source Data: set the tracker field on which computation of the Pie graph will be based. 90
  • Codendi User Guide Creating / Editing a Bar graph Specific informations available for the Bar graph are as follows: • Width and Height: set the size of the graph in pixels. • Source Data: set the tracker field on which computation of the Bar graph will be based. • Group by: set a tracker field by which computation of source field will be grouped. 91
  • Codendi User Guide Creating / Editing a Gantt graph Specific informations available for the Gantt graph are as follows: • Start Date: set the tracker field for the start date. • Finish Date: set the tracker field for the finish date. • Due Date: set the tracker field for the due date. • Time Scale: can be day, weak, month and year. • As of date: Date considered as a reference for data display. Default value is today. • Summary: Text to be displayed on the gantt left, and in the bar tooltip. • Progress: Percentage of completion of the task. Must be an integer field display in a Text Field, with values between 0-100. • Informations at the right of the bars: Text to be displayed at the right of the gantt bars. 92
  • Codendi User Guide 7.13.10 Email Notification Settings As explained earlier in Section 7.8 [page 60] the Codendi Tracker comes with a predefined set of rules to keep relevant people aware of the artifact life. The default rules can however be com- plemented or tuned in a number of ways: Global Email Notification In addition to the default notification rules, the tracker administrators have the ability to specify a list of comma separated email addresses to which submissions of new artifacts (and optionally artifact updates) will be systematically sent. Note that in this case notifications will be sent to users regardless of their personal preferences defined (see section "Event/Role Based Notifica- tion Settings" below). You can choose to disable the permission check for global email notification. This can be useful if the email address is a mailing list, because individual permissions can't be checked for each member of the mailing list. So for mailing lists, if the check box "check permissions" is checked, the notifications will be send to each member with the permissions of an anonymous user. This feature is typically used to send submissions of new artifacts to a number of well identified persons in the team who are in charge of qualifying and dispatching the artifacts. Tip: Create a Distribution List to notify several people If you want to notify many people at once, we suggest that you use the Codendi Mailing Lists service to create a distribution lists (see Section 15.1 [page 170]). Once the Mailing List is up and running type the e-mail address in the Global Email Notification field. Creating a Mailing List on Codendi has several advantages: first individuals can (un)subscribe by themselves and second all messages sent to a Codendi mailing list are kept in an archive that can serve as an audit trail for your tracker. 93
  • Codendi User Guide Tracker Watchers The Codendi Tracker offers to all project members the ability to be carbon-copied on all email notifications sent to some other project members. Here are a couple of examples where the tracker watch feature can be extremely useful: • Backups: when a team member is away from the office it is often convenient to dele- gate her artifact management activity to another person in the team who is acting as a backup. Becoming the backup of another team member is as easy as inserting her name in the Watchers field of the backup person when the team member quits and re- move it when the team member returns. As soon as you specify a person name in the watchers field you'll start receiving all the artifact notification of this person and you can act accordingly on her behalf. • QA Contacts: another possible use is for the QA team members to fill the tracker watcher field with the names of the software engineers whom QA activity they are re- sponsible for. Remark: The goal of the tracker watch feature is not to spy on you. To make sure that you are only watched by authorized persons, Codendi always shows you the list of Codendi users who are currently watching your email notifications. Event/Role Based Notification Settings This is the most sophisticated part of the customization process. It allows any user to specify what types of events they wants to be notified of by email. Note that these settings are project and user specific so you can tune your own email notification preferences for each tracker you are involved with. The customization matrix (see Figure 45 [page 95]) presents you with a series of check boxes. Each check box allows you to specify what kind of events you want to be aware of depending on the role you play with respect to the artifact. There are 4 roles defined with respect to an artifact: • Submitter: you are the person who initially reported the artifact by filling out the artifact submission form. • Assignee: you were assigned the artifact and you are therefore responsible for manag- ing it. • CC: you are mentioned in the list of CC names (see Section 7.5.3 [page 54]). • Commenter: you have once posted a follow-up comment in the artifact. For each of these roles you can instruct the Codendi Tracker to send email notifications to you only when some specific events occur. Nine different events (see the right most column on Fig- ure 45 [page 95]) are monitored by the Codendi Tracker. The description of the events is self ex- planatory and only appeal one comment: the first 8 events in the list can only occur on artifact updates. Only the last event relates to the submission of a new artifact. Let's review the sample matrix shown on Figure 45 [page 95] and see, step by step, how this user has configured her notification settings: 94
  • Codendi User Guide • First let's look at the Commenter column. The Commenter column says that this user has decided that if she is involved in an artifact as a Commenter (she just posted a fol- low-up comment at some point in time) then she is only interested in receiving email no- tification when the status of the artifact goes to "Closed" or when any of the fields Prior- ity, Status and Severity is modified. All other events will be ignored by the Codendi tracker and no notification will be sent to this user. • Second, looking at the matrix by row, one can see that the user said that when she makes a modification to an artifact herself (Event "I am the author of the change") she doesn't want to receive any email notification whatever their role in this artifact is. Please note that the event "I am the author of the change" overlaps with other events. So in our example, the submitter will not get a notification when she adds a new artifact. Even if the event "A new artifact has been submitted" is marked • Finally, the user also said that when a new artifact is submitted to the project and is im- mediately assigned to her (Assignee role), she wants to be notified. However if she is the submitter of the new artifact then she is not interested in receiving the notification. Note that the Commenter role is meaningless for the event "A new artifact has been submitted" because follow-up comments can only be added at update time not at cre- ation time. Also, the event "I'm added or removed from this role" is meaningless for the Submitter and the Commenter because these roles can not be modified in an artefact. Figure 45. Configuration of the Personal Notification Matrix Suspend Email Notification Sometimes, it can be convenient to suspend all email notifications for one specific tracker, for instance during maintenance tasks. By selecting this option, a tracker administrator disables both global notifications and event/role notifications. This feature is typically used when doing mass-changes or for testing purposes. 95
  • Codendi User Guide CHAPTER 8 File Release 8.1 Source Code Release: Guidelines There are 2 ways by which project administrators can provide access to their project source code on Codendi: the software configuration management repository (CVS or Subversion) and the File Release mechanism. At first glance, having two distinct Codendi services seems redun- dant. However both have been developed with different objectives and target audience in mind and they are very much complementary. Providing both is definitely a plus for your visitors. • The SCM repository provides a full access to your source code including its entire ver- sion history. However accessing the source code via SCM tools requires that the Co- dendi user installs specific software on his machine. Not everybody is capable or willing to do so. SCM access is well suited for Codendi users who want to get deeper in the project code, add some new extensions, fix bugs and contribute changes back to the project team. Please be aware that certain projects decide to restrict the access to the SCM to project members only. Hence the importance of the file release mechanism. • The File Release mechanism allows you to deliver pre-packaged version of the source code and/or binaries in one or several archive file (zip, tar, jar,...) that an authorized user can easily download from the Codendi Web site. No specific tools or knowledge is re- quired. Besides possibly providing pre-packaged source code it is also considered a very good practice to provide ready-to-use binary version of your software to make de- velopers life even easier. The File Release service is well suited for people who want to start using your software without any further delay. As you can see both services are fundamentally different in nature and we strongly encourage project teams to use both of them. In order to help project teams understand why these two ser- vices are highly complementary a typical project life cycle is documented on Figure 54 [page 113]. 8.2 File Release Jargon Before we get further into the description of the File Release service let's review the terms used throughout this section. These terms are key for the understanding of the File Release mecha- nism both for users and administrators (see Figure 46 [page 97]). 96
  • Codendi User Guide Figure 46. The File Release Structure • Packages :These are the topmost entities visible in the File Release service. A package is a container for one or several Releases. In general a package do correspond with high-level deliverables of your software products. Let's assume that your team is work- ing on a database engine. Possible packages could be DB-engine for the database en- gine itself and DB-drivers for the database drivers like ODBC or JDBC drivers. A third package DB-Docs could also be created to deliver the documentation in a separate con- tainer. • Releases: A release is a collection of individual files that were all frozen and time stamped at a given moment in time. In that sense it is also a container like a package but one level below. The files contained in a release generally correspond to a given version (also called release) of your software. Building on the database example above we could imagine than the DB-engine package has release 1.0, release 1.1 and release 2.0beta available. DB-drivers could have release 1.0 as well but no release 1.2 because the 1.0 drivers also work with the release 1.2 of DB-engine. In other words release nam- ing can be completely independent from one package to another. • Files: files are the basic entities that one can find in a release. Again building on the database engine example, we can imagine that the release 1.0 of package DB-engine contains the file db-engine-src-1.0.zip for the source file and db-engine-win32-1.0.zip for the pre-compiled Windows version. When release 1.2 of the DB-engine package pops up, we could have files db-engine-src- 1.2.zip for the source file and db-en- gine-win32-1.2.zip for the pre-compiled Windows version and a new file called db- engine-linux-intel-1.2.zip for the pre-compiled Linux version running on Intel hardware. We haven't said a word about the DB-docs package. May be it is still empty for the mo- ment ;-) At first glance, this structure may appear a bit complex. However this is really the kind of struc- ture a project team should aim at to make their deliverables easy to understand and easy to ac- 97
  • Codendi User Guide cess for the community. Thinking about the structure of your software and documentation deliv- erables ahead of time can help you structure your team, your working processes (e.g. build and test process) in the right way. Do not overlook this part of your project. 8.3 File Release Browsing and Download The latest version of each project package (if any) is always visible on the Project Summary page (see Figure 7 [page 23]). The latest version can immediately be downloaded by clicking on the "Download" link or visit the complete list of packages and release by clicking on the "[View ALL project files]" link. Figure 47. The File Release screen of the Codendi Administration project The first example given on Figure 47 [page 98] shows the File Release screen of the Codendi Administration project. 8.3.1 Browsing packages As explained in the Section 8.2 [page 96], projects can contain several packages. In the exam- ple, the project has three packages called "Codendi Installation ISO Image", "Codendi specifics themes" and "Codendi CLI". 98
  • Codendi User Guide The content of each package can be hidden by clicking the minus icon located just before the package name. This can help for visibility reasons if your project has lots of packages and re- leases. To expand a collapsed package, simply click the plus icon before the package name. By default, all the packages are expanded. Codendi gives you the opportunity to monitor the packages. Like this, you will be notified when a new release is available, or if a release is updated, etc. In order to monitor a package, click the bell icon located after the package name. If you're already monitoring the package, there is a red sign on the bell. If you don't monitor the package, the bell has a green plus on it. 8.3.2 Browsing releases A package can contain several releases. In the example, the package "Codendi Installation ISO Image" contains 8 releases from 2.4 to 3.0.1 listed in chronological order. Each release contains a certain number of files. Like packages, the content of the releases can be hidden to enhance visibility. The mechanism is the same: click the plus and minus icons to expand/collapse the release content. By default, only the first release of each package (which is the latest one) is expanded. After each release name, the icon representing a text file let you read the notes and the changelog of the current release. 8.3.3 Downloading files Each release contains a certain number of files to be downloaded. In the case of the release 3.0.1, two ISO image archives can be downloaded. Files that belong to the other releases are hidden in this example. To make them visible, just click the small plus that stands just before the name of the release. Some file information is given, like the size, the type of file, the architecture (if it is relevant) the date and the number of downloads. To download a file, you just have to click the name of the file and follow the instructions. 8.4 File Release Delivery and Administration This section is for project admins and file admins only. It goes through a detailed explanation of the File Release delivery process. This is a 2-step process: 1. Package Creation: Create one or several packages. This must only be done once. When packages are in place you can add a new release or update an existing one in them at any time. 2. Release Creation: Once a package has been created, you can add (and update) re- leases to it When you are project admin or file admin, you are able to perform the admin actions on the File Release System home page. (See Figure 48 [page 100] 99
  • Codendi User Guide Figure 48. The File Release screen of the Codendi Administration project, when you are admin 8.4.1 Package Administration To administrate packages, you must be project admin or file admin. Package creation and modi- fication are nearly the same. Package Creation To create a package, you just have to click the [add a package] link located on the top of the File Release screen. Then, fill the form, giving the package name, its relative rank on the File Release screen, and its status: • Package Name: this is the name of the package. The name of the package must be unique in a project. • Rank on screen: the rank indicates the position the packages will be displayed in the screen. You can choose the value: 'at the beginning', 'at the end', or after every other package. • Status: an active package will be displayed, whereas a package with a hidden status won't appear on the File Release screen. For project admins or file admins, the hidden packages are displayed in italic, in order to update them. Package Modification To update a package, just click the [edit] icon located after each package name. Then, the mod- ification form is the same than the creation one, except that you can set read permissions on the package (see Figure 49 [page 101]). 100
  • Codendi User Guide Figure 49. Package Edition Screen of the CLI package, in the Codendi Administration project A project member with the 'File Manager Admin' right (see Section 6.9 [page 33]) can attach ac- cess permissions to any existing package. By default, permissions attached to a package apply to all releases and files that belong to this package. But you may also set different permissions to specific releases (see below). 8.4.2 Release Administration To administrate releases, you must be project admin or file admin. Release creation and modifi- cation are the same. Release Creation and modification Once a package has been created you can immediately start adding releases to it. Click on the [Add a Release] link of the appropriate package (see Figure 48 [page 100]). The release creation and modification process is really easy to perform. It can be divided into 6 steps, but some are optional. (see Figure 50 [page 102]). In every case, you can update the re- lease at any time 101
  • Codendi User Guide Figure 50. The release update screen of the Codendi project • Step 1 - Give Release properties The first step is the only one mandatory to create a release. It gives you a chance to modify the package of the release, the release date, and the status of the release. You also have to provide the release name. • Step 2 - Upload and attach files to the release (optional) This step is optional in the way that you can add the files after having create the re- lease, but of course, a release should contain at least one file to be relevant. As ex- plained above multiple files can be attached to the same release. To attach a file, click the [add file] link. Then, a select box appear, in order to select the file to attach. There is two solution to attach a file: • Direct Upload: you can upload the file via the Web interface by using the "Local file - Browse" option in the pull down menu and pointing to the appropriate file on your lo- cal disk. • FTP / SCP: upload your file via ftp or scp and then select the appropriate file name from the "FTP/SCP Files list " in the pull down menu. Tip: How to upload files using FTP or SCP Codendi server offers an upload mechanism via FTP (ou SCP). To upload your files, follow the in- structions given when you click the ? next to the [add file] link. Then click the [Refresh File list] link to see your files. 102
  • Codendi User Guide • Step 3 - Add Release Notes and/or Changelog (optional) With the release, you can also provide notes or changelog, and even both! You can ei- ther cut and paste or upload Release Notes and ChangeLog. To upload a release note or a changelog, click the Upload link. The Release Notes is typically a short (10 to 20 lines) and high-level document that summarizes the new features delivered in this release with a focus on the user visible changes (new UI, new functions, new APIs...). This is an important document and all new releases should definitely have one. Release Notes are immensely helpful to the community to determine whether they need to upgrade to the next release. The ChangeLog is a much more technical document. It contains all bugs fixed in this new release as well as any change in the design or the architecture. This document is not as critical as the previous one to the normal end-user but it is absolutely pivotal for those who use your software in other development or integration activities. Tip: Generate a Changelog file easily If you use CVS as you version control system you can very easily generate a well formatted and in- formative Changelog file. The cvs2cl utility available at http://www.red- bean.com/cvs2cl automati- cally extract all the CVS commit messages, aggregate them with modification dates and author name and format them in a nice way. This is a very good basis for a Changelog document. • Step 4 - Set permissions to the Release (optional) By default, releases have no specific access permissions: access to all files is granted to any Codendi registered user (anonymous users are not allowed to download release files). However, in some cases, you might want to limit the users allowed to download your software. In these specific cases, you can restrict access permissions to your pack- ages and releases to specific user groups. See Section 6.10 [page 35] for more informa- tion on user groups. To define or to change the permissions on a release, click the [view/change] link in the permissions frame. Package and release permissions are enforced at two different levels: • File List: When a user is not granted access to a package or release, then the pack- age or release is not listed in the 'File' main page, so s/he does not know that the file exists. • Download: If a user finds or forges a download link for an unauthorized file, the download will still fail. The system systematically re-checks for permissions when files are requested for download. If you do not specify any access permissions for a release (or reset them to default), it inherits the access permissions from the package it belongs to. However, when you de- fine a permission for a release, then it overrides the permissions defined for the pack- age. The permissions set for the release can be only stricter than the package permissions. • Step 5 - Submit a News (optional) 103
  • Codendi User Guide This step is optional in the sense that you can skip it if you want. This step gives the op- portunity to project admin to submit a news about the release they've just created (if you're not project admin or news admin, you won't see this step). A default subject and message are pre-filled. You are of course free to modify it. The news will be displayed on your project summary page. It is a good way to advertise the users that a new re- lease have been done. The news will also appear in the news administration page, like others. • Step 6 - Send e-mail notification (optional) This step is optional in the sense that it may not show up on your screen. If some Co- dendi users monitor your package, this step will tell you how many of them are doing so. Codendi gives you the freedom to send an e-mail notification or not to the users who ex- pressed interest in your packages. Do not bypass this step, always inform your commu- nity of users and developers. Tip: Always include a useful README file When you prepare your files for release make sure that you include a README file in the top direc- tory of each file that a user can download. And pack this README with useful information like the address of your Codendi site, the Mailing list you have put in place for your project, how to submit a bug or a support to the project team (via Codendi of course) 8.5 Processor List Administration Project admins and file admins can manage the processor list per project. The processor is an (optional) attribute of a released file. Depending the project or working domain, you could be in- terested in adding processors to the existing list. To do it, follow the admin link "Manage proces- sors" of the File Release System. Then, you have the list of the available processors. System processors are not editable. The other processors are specifics to the current project. You can edit them, delete them, as well as create new ones. A processor has a name and a rank in the processor list. 104
  • Codendi User Guide CHAPTER 9 Version Control with CVS This chapter is not a CVS Tutorial. It focuses on the integration of CVS with Codendi and how to use it in an optimal way in this context. If you are not familiar with the CVS version control sys- tem look at the CVS references (see Section 9.1.2 [page 107]). It is important to note that version control is just a part of the overall configuration management activity. Therefore, CVS alone does not constitute a complete configuration management solu- tion for your project. Depending on the maturity of a project, the project may have specific poli- cies regarding use of the CVS baseline or the integration of bug fixes, etc. Projects should make sure that project members know and follow these policies. For example, a project may wish both to commit changes daily to avoid loss of work, and to also insure that the baseline is always unit tested code. Since the end of the day may arrive before the code or unit tests are complete, a single baseline cannot accommodate both uses, so the project may opt to use CVS branches. Don't worry if you do not initially know enough to write the final policy for your project - this al- ways tends to evolve as the project matures - but do communicate regularly with the project members and improve your configuration management plan on a regular basis. 9.1 CVS: Concurrent Version Control CVS stands for Concurrent Versions System. It allows a team of multiple developers to concur- rently manage their own version of the same source code and gracefully merge the changes brought to the software by the various team players. CVS can help you track the changes in the history of your project. No good software project should be started without making a decision on which version control tool is going to be used. CVS and Subversion (see Chapter 10 [page 120]) are the two possible choices offered by Codendi 5. Although Subversion is a more modern version control system, using CVS is a very valid choice for several reasons: • It has an elegant and efficient client/server architecture that makes it usable from any- where on the Intranet. • It runs on almost every hardware platforms and Operating Systems available on the market today (Linux, Unix, Windows, MacOS...). • It is a bullet proof version control system that is being used by literally hundreds of thou- sands of software projects, whether Open Source or commercial throughout the world. • It can be used in a command-line mode or through one of the many graphical user inter- face front-ends. • It is very good at minimizing disk storage space on the server side and network band- width consumption between the client and the server. Working with CVS over a modem 5There are many version control software available on the market whether Free Software (SCCS, RCS, PKS, Arch, Monotone......) or Commercial (SourceSafe, ClearCase, TeamWare...) 105
  • Codendi User Guide connection is perfectly feasible. • Out of the box it can support small to mid-size projects well, and can be configured and extended to support most any size project. • And last but not least, it is a fully Open Source software distributed under the GNU GPL License. 9.1.1 CVS Clients CVS has a client-server architecture. In other words, Codendi developers who want to interact with the CVS repository of their project must have CVS installed on their desktop machine, hereafter called client. The Codendi server permanently runs a CVS server in the background to which CVS clients talk to to act upon the CVS repository. CVS clients come in various flavors for all sorts of platforms (Windows, Mac and all Unix): command line interface, graphical based in- terface and web based interface. Command Line Interface CVS originates from the Unix world and therefore all the CVS functions can be controlled from a command line interface. Even though CVS has multiple command line options, most commands that you normally use have one or two command-line options and are very easy to remember. Refer to Section 9.1.2 [page 107] for more information about how to use CVS. Graphical Front-ends Many CVS graphical front-ends can be used on your client workstation. There are clients for all platforms: Windows, Linux, Unix and Mac. WinCVS and Tortoise seem to be two of the most well known clients for Windows platform (see below). On Linux, gCVS and Cervisia are the most popular. There is also a 100% Java client called jCVS that runs on any machine supporting JDK (or JRE). And finally, for those of you who use Emacs or Xemacs as an editor you'll probably want to use the excellent pcl-cvs package, which provides full CVS integration on these editors. Many commercial text editors also offer tight integration with CVS. Finally it's worth noticing that most integrated development environment on the market (MS Vi- sual Studio, Visual Age, IntelliJ IDEA, Eclipse,…) comes with CVS plugins either provided na- tively or by 3rd party companies. Setting up WinCVS for Codendi As mentioned above, WinCVS is one of the most popular CVS clients on Windows. Below are all the instructions needed to get WinCVS running on a Codendi project. In the examples, "user- name" is the user login name, and "projectname" is the short project name. • Download WinCVS from http://www.wincvs.org and install it on your PC. • Run WinCVS: Start->Programs->WinCvs • Setup the connection to the Codendi project: Admin->Preferences Enter the CVSROOT: :pserver:username@cvs.projectname.www.codendi.org:/cvsroot/projec tname 106
  • Codendi User Guide Make sure the Authentication is set to: "passwd" file on the cvs server Then hit OK. • Log in to CVS: Admin->Login... Enter your password. • Identify the place where you are going to install the source code: View->Browse Lo- cation->Change... • Checkout the source code from the CVS repository of your Codendi project: Create->Check out module Enter the module name and path on the server: type the path of the source code you want to extract. In general it's the name of the top directory of your CVS repository. then hit OK. Note that this may take a while for large projects • Now that you have the source code of the project on your machine you can start modify- ing the code, update it with new modifications from the repository, etc. WinCVS keeps track of changed files by marking them with a red icon. Other things to know about WinCVS: • If someone modifies a text file at the same time you do, and checks it in first, then when you go to check yours in, the lines that you both changed independent of the other will automatically get updated to the latest changes. If any lines conflict, you'll get an error message letting you know that there were conflicts, and that your version of the file will need to be modified to resolve the conflicts. You'll also find lines in your version with ">>>>>>" and "<<<<<<" delimiting the conflicts. Edit the conflicts, then re-commit. • Be careful with the "remove selected" (the big black X), which doesn't delete your local version of the file, it queues the file for removal from CVS. 9.1.2 CVS References As stated earlier in this chapter, this document is not a CVS Tutorial. It focuses on the integra- tion of CVS in Codendi and how to use CVS in the Codendi context. If you want to learn more about CVS refer to the following documents: • Open Source Development with CVS : excellent book also known as "The CVS Black Book". Also available in printed form from Coriolis Press. See http://cvsbook.red-bean.com/. • The official CVS Manual. Otherwise known as the "Cederqvist" after the name of the au- thor. See http://www.cvshome.org/docs/manual/index.htmlThis document is also con- tained in the CVS software releases - see below. • Various CVS Docs and FAQs. See http://www.loria.fr/~molli/cvs-index.html. • The Official CVS Web Site. See http://www.cvshome.org/. 9.2 CVS Integration in Codendi 9.2.1 The CVS Repository 107
  • Codendi User Guide Whenever a new project is hosted on Codendi, a new CVS repository is automatically created and properly initialized. Each project has its own CVS repository. Having its own repository has a certain number of advantages: your CVS logs, history files (CVSROOT/history), and all ad- ministrative files are unique to your repository. This allows you to fully customize the behavior of your CVS repository. All CVS repositories are available under the /cvsroot/projectname directory on the Co- dendi server. All interactions with the CVS repository take place from a CVS client through the cvs program. If need be and if this feature is active on your server, you can also use your shell account (see Section 18.1 [page 189]) to interact with the CVS repository directly but you should never do that unless you know exactly what you are doing. 9.2.2 CVS Access Control CVS access permission depends upon the project status (private or public) and the class of citi- zen a user belongs to (see Section 3.1 [page 13]). Regarding private projects, only project members have access to the CVS repository. By default they all have read and write access. This can be modified by adding in the CVSROOT/readers file the name of the project member for which only read access is granted. It is currently not possible to deny access to the CVS repository to a member of a private project. If you want to do so or want to setup more sophisticated access control permission we highly recommend that you use Subversion instead of CVS (see Chapter 10 [page 120]). With respect to the public projects, the default access permissions are as follows: • Anonymous Users: users who have not registered with Codendi (or are not logged in) have no access at all to the CVS repositories. Depending on the configuration of the Co- dendi server, anonymous user may even be denied access to the entire site. • Registered Users: have read-only access to CVS repositories. In other words they can checkout a working copy of the software but they are not allowed to commit any changes they have made to the source code. Source code contributions (bug fix, en- hancements…) from this class of user must return to the project team via the Patch Tracker (see Section 7.12.2 [page 66] ). Note: all source code accesses are recorded by Codendi. Project administrators always have access to the list of people who accessed the source code (see Section 6.14 [page 42]). • Project Members: members of a Codendi hosted project are granted a password pro- tected read/write access. As mentioned above in the section about private projects, it is also possible to grant read-only access to the project members. • Project Administrators: same as project members. 9.3 The CVS Web Interface Codendi offers a number of facilities that allow you to interact with your CVS repository through the Web interface. The CVS Web interface does not intend to replace the CVS client that you should normally use on your desktop computer. It rather focuses on providing you with addi- tional features not found in cvs clients. The CVS Web interface can be accessed via the "CVS" item in the Project Main Menu or via the CVS service listed in the Public Area (see Figure 7 [page 23]). The Codendi CVS Web interface provides the following features: 108
  • Codendi User Guide • Accessing the CVS repository: The welcome page of the Codendi CVS service gives you all the information you need to access the CVS repository from your CVS client. Among other things it tells you what the CVS root path is and how to log in and check- out the source code. This page may also be customized for specific needs (see Section 9.3.4 [page 112]). • Browsing the CVS repository: this feature allows you to browse the CVS repository even if you don't have a CVS client installed on your desktop machine. • Querying CVS : if the CVS tracking feature has been activated for your project (default) all CVS events (commit, file addition or deletion) are tracked down in the Codendi database. This audit trail can be searched using several criteria. • CVS Administration : this service allows you to activate the CVS tracking for your project, to enable cvs watch mode, to activate email notification for all CVS events, and to customize the CVS welcome page (CVS Preamble). Let's review some of these features in more details: 9.3.1 Browsing The CVS Repository In order to interact with the CVS repository of any Codendi-hosted project, you normally need to have CVS installed on your machine. However Codendi also offers a built-in Web browsing in- terface to the CVS repository which allows you to navigate in the source code, download it, view a file history or compare two revisions of the same file. Figure 51. Browsing the CVS repository - A sample session 9.3.2 Querying CVS If a project has the CVS Tracking feature activated (see Section 9.3.4 [page 112]), the CVS Web interface will bring very useful features to the software engineers: 109
  • Codendi User Guide • Atomic CVS commit and unique commit ID: all changes (file modification, addition or removal) that are committed in one go from your CVS client will be assigned a unique commit ID. All file revisions modified during this commit will be stored atomically in the CVS Tracking database under this unique commit ID. • Commit cross-referencing: the unique commit ID that is generated at each commit can be referenced in future commits, or in the follow-up comments of project artifacts like bugs/tasks/support requests simply by using the pattern commit #XXXX (where XXXX is the unique ID generated by Codendi). Any reference of that kind will be auto- matically transformed into an hyperlink to the CVS tracking database. This mechanism makes it very easy to go from project artifacts like bugs, support requests or tasks to source code changes and vice-versa. (see below for more details) • Commit search: another side benefit of the CVS Tracking database is that you can use various search criteria to query the database. You can search code changes by authors (who made the change), by commit ID, by tag or by keywords to be found in the log message. Results can also be sorted by clicking on the headers of the search results (see Figure 52 [page 110]). A click on one of the selected commit ID brings you to a complete description of the change, the files that were impacted and the nature of the change with a direct link into the CVS repository if you want to browse the file or look at the code modification (see Figure 53 [page 111]). Figure 52. Querying the CVS tracking database of a given project 110
  • Codendi User Guide Figure 53. The detail of an atomic CVS commit 9.3.3 Cross-Referencing Artifacts and CVS Commits While working in the development or the maintenance phase of a software project, it is vital to keep track of the changes made to the source code. This is what Version Control systems like CVS do. In addition to keeping track of the source code change history it is often critical to relate the changes to the artifact (a task, a defect or a support request) that led the developers to make a change in the code. And conversely, when reading the artifact description it is also very helpful to immediately see how the change was implemented. The integration of CVS in Codendi precisely provide the Codendi users with this bi-directional cross-referencing mechanism. This is achieved through the use of reference patterns that are automatically detected by Codendi in either the follow-up comments of the project artifacts or in the messages attached to a CVS commit. The text patterns to type in a commit message or a follow-up comment are as follows: • XXX #NNN: this pattern refers to the artifact XXX number NNN, where NNN is the unique artifact ID, and XXX is the tracker short name (e.g. "bug #123", "task #321", "req #12", etc.). If you don't know the tracker short name or don't want to specify it, you may simply use "art #NNN". When browsing a message containing this pattern anywhere in Codendi, the pattern will be automatically transformed into an hyperlink to the artifact description. • commit #YYY: this pattern refers to the commit YYY where YYY is the commit unique ID as listed when querying the CVS tracking database. When browsing a message con- taining this pattern anywhere in Codendi, the pattern will be automatically transformed into an hyperlink to the commit description (log messages, impacted files, versions and author of the change. • The Codendi reference mechanism allows cross-referencing with any Codendi object: artifacts, documents, files, etc. Please refer to Section 6.8.1 [page 30] for more details 111
  • Codendi User Guide on Codendi references. Tip: cross-reference artifacts and CVS commits It is considered a best practice to always reference a bug, a task or a support request in any of the log message attached to a CVS commit. Similarly when closing the related artifact (task, bug,etc.) make sure you mention the commit ID in the follow-up comment. You will find this extremely conve- nient while trying to keep track of the changes and why it was made. 9.3.4 CVS Administration Through the Web interface, Codendi allows you to configure the following settings: • CVS Tracking: Being a version control system CVS is, of course, natively taking care of all your file history and is able to tell you what changes were made by whom and at what date. The file history is something you can look at either through your CVS client or through the CVS Web Browsing interface. If you activate the CVS tracking for your project Codendi will also keep track of all the code changes in the Codendi database. This will give you extra capabilities on your CVS repository as explained in Section 9.3.2 [page 109] • CVS Watch Mode: Watches in CVS work as a communication device, CVS can be used to keep participants informed about what's going on in a project by using "cvs watch add", "cvs watch remove", "cvs edit" and "cvs unedit" commands. The watch features depend on the cooperation of all the developers. If someone just starts editing a file without first running "cvs edit", no one else will know about it until the changes get committed. Because "cvs edit" is an additional step, people can eas- ily forget to do it. Although CVS can't force someone to use "cvs edit", it does have a mechanism for reminding people to do so with the "watch on" command. If you enable CVS Watch mode on your project, future checkouts of this project will be read-only, so it will remind developers to use "cvs edit" before editing a file and it will allow other developers to be informed of the file changes. Watch mode will be effective in maximum two hours after you change its value. Be care- ful : if you enable or disable watches by command line (not by the interface) the watch mode in the CVS administration won't be updated. • CVS E-mail Notification: In addition to tracking the changes in the Codendi database, Codendi can also send a nicely formatted email message to individual email addresses or mailing lists each time there is a change in your source code. The email message contains the log message, the author of the change, the list of impacted files and point- ers to the CVS repository showing what changes were made. • CVS Preamble: In some cases (e.g. for legacy projects), the project CVS repository might not be hosted by the Codendi server. In this case, the CVS information displayed in the welcome page of the Codendi CVS service is incorrect. Fortunately, the project administrator can customize the CVS preamble here. Tip: create a specific mailing list for CVS events notification 112
  • Codendi User Guide If you intend to generate email notification for the changes made in your CVS repository, it is a good practice to create a specific mailing list called projectname-cvsevents. By doing so, Codendi users and project members interested in receiving the email notification just need to subscribe to the mailing list. In addition, the Codendi mailing list manager will archive all the email messages which can prove very useful for future reference. See Section 15.1 [page 170] for mailing list creation. 9.4 A Typical CVS Life Cycle Again the intent of this section is not to give formal CVS training but rather to explain what are the steps a project team typically goes through to efficiently use CVS and, more generally, all the Codendi tools involved in a Software release process. It also deals with the problem of contributing source code when you are not part of a project team. In this section all examples are given in the form of CVS command lines but transposing them to graphical front-ends should not be a problem. Figure 54. A Typical Software Development Life Cycle on Codendi 9.4.1 Logging In Audience: all Codendi users The first step when dealing with a Codendi-hosted CVS repository is to authenticate yourself with the CVS server. In Codendi, anonymous users cannot access the source code of any project whether be it through the CVS repository or through the File Release mechanism. So make sure you have created your own account on Codendi before interacting with a CVS repos- itory. 113
  • Codendi User Guide Assuming that you have your Codendi login/password ok, you can now use them to authenti- cate yourself with the CVS repository. To connect to the CVS repository of a given project type the following command (in one line): cvs -d:pserver:loginname@cvs.projectname.www.codendi.org:/cvsroot/projectname login Where: • The -d argument is called the CVS root path. This path is a sort of URL to locate your CVS repository on the net. CVS graphical front-ends will also ask you for this root path. • projectname is the project short name • loginname is your Codendi login CVS keeps track of the password associated with a given CVS root path. So as long as you do not logout there is no need to authenticate yourself in subsequent working sessions. If you don't want to leave your CVS connection "open" when you leave your office, use the "cvs logout" command. 9.4.2 Importing Existing Source Code Audience: project members As the happy administrator of a new Codendi project, the first thing to do is to populate your freshly brewed CVS repository with your project source code. To do so, first create a new direc- tory topdirectory on your workstation and place your source code under this top directory (keep the exact same directory structure you are used to under topdirectory). Then type the fol- lowing commands (the second command in one line): $ cd topdirectory $ cvs -d:pserver:loginname@cvs.projectname.www.codendi.org:/cvsroot/projectname import topdirectory vendor_tag start Where: • The -d argument is called the CVS root path. This path is a sort of URL to locate your CVS repository on the net. CVS graphical front-ends will also ask you for this root path. • projectname is the project short name • loginname is your Codendi login (all lowercase) • topdirectory is the name of the top level directory to import • vendor_tag is a special tag. For now replace it with your own name or your company name (without space). Tip: made a mistake while importing your source code? It is not unusual to make a mistake when importing your source code into a fresh CVS repository es- pecially for new users. Typical mistakes are directories placed at the wrong level or with the wrong name. Nothing to fear though... if you want to start again on a new CVS repository contact the Co- dendi Team and we'll do that for you. Note that if you already have a CVS repository available, the Codendi Team can help you trans- 114
  • Codendi User Guide fer this repository on Codendi and preserve all of your project history. We just need an archive (zip or tar) of your entire CVS tree including the CVSROOT directory. From there we'll re-install everything for you on the Codendi server. Contact us for more information. 9.4.3 Checking Code Out Audience: all Codendi users Once a CVS repository has been populated project members (or Codendi users at large if they are granted access) can checkout the source code and place it on their own workstation. The result is called a working copy in the CVS jargon. Note that 'checkout' in the CVS world does not mean that the user has acquired any sort of lock on the file. The CVS paradigm is: anyone (with the right permissions) can retrieve a working copy for editing; changes made by different users are then reconciled or flagged for conflict resolution whenever the modified files are locally up- dated. As its name says it and unlike other tools (RCS, SCCS, ClearCase...) CVS is a concur- rent version control system. A working copy is NOT an image of the CVS repository. It is rather a snapshot of the source tree at some point in time and, by default, it's the latest version at the time the working copy is created or updated. One of the interesting features of a working copy is that it is a self-contained entity. In other words, a working copy contains all the necessary information for CVS to know exactly which CVS server and repository it is coming from and the corresponding moment in the history of the source tree . This is also why you won't see the -d command-line option in all sub- sequent CVS commands presented here. These commands run from within a working copy, so CVS knows exactly where the CVS repository is. To create a working copy type the following command: cvs -d:pserver:loginname@cvs.projectname.www.codendi.org:/cvsroot/projectname checkout directory Where: • The -d argument is called the CVS root path. This path is a sort of URL to locate your CVS repository on the net. CVS graphical front-ends will also ask you for this root path. • projectname is the project short name • loginname is your Codendi login (all lowercase) • directory is the path to the directory that you want to checkout. To learn more about the directory structure of the CVS repository you are working with, first browse the CVS repository via the CVS Web Interface (see Section 9.3 [page 108]) 9.4.4 Updating the Source Code Audience: all Codendi users Running a "cvs update" command from within a working copy has the effect of updating the working copy (or a subpart of it) with the latest version of each source file from the CVS reposi- tory. To update a working copy with terse output mode type: cvs -q update If you simply want to know what files have changed on the CVS repository since your last up- 115
  • Codendi User Guide date but don't want to update your working, you can run the cvs command with the "show- me-but-don't-do" flag (-n): cvs -n -q update Remark: The CVS update command is among the most semantically rich in the CVS command set. It is used not only as described above, but also to merge your working copy with another version of the software, possibly changing the branch to which your working copy points. Refer to your CVS documentation for complete details. 9.4.5 Committing your Changes Audience: project members Project members involved in development activities will likely want to contribute the changes made in their own working copy back to the CVS repository. In CVS terminology this is called a commit operation. To commit changes you have made in your working copy, type the following command: cvs commit -m"Explain the nature of the change here..." [filenames] Where: • The -m option is followed by a text message explaining what changes you have made • The filenames argument is optional. It can be individual files or directories. But if there isn't any argument cvs will automatically commit all the files that have changed in the di- rectory where you are located and all sub-directories recursively. Tip: Include a bug or task number in your commit messages In the ideal world, all modifications made to the source code of a project should be related to either a bug logged in the Codendi BTS or to a task assign to a developer. If your project team lives in this wonderful world :-) then don't forget to include the related bug or task ID number at the beginning or at the end of your commit message (see Section 7.5.6 [page 56]). The CVS administrative files can help you enforce this rule by checking the format of all the submitted commit messages and reject them if it does not follow the recommended pattern. As a project member, make sure you understand and follow your project policy before you com- mit any changes to your CVS repository. For example some projects require that only working, build-able, code that passes automatic unit tests be checked into the main branch. Thus the baseline can automatically be built and unit tested nightly. Tip: update before you commit If you try to commit a modified file that was also modified on the CVS repository in the meantime, the CVS server will refuse to execute the cvs commit command. You must first execute a cvs up- date command to bring your own working copy up to date with latest version, merge your changes with those from others (CVS does it automatically in most cases) and then only commit your own changes back to the CVS repository. If you want to be immune from others' changes then create a CVS branch and work with it in isolation. 116
  • Codendi User Guide 9.4.6 Contributing your Changes (other users) Audience: all Codendi users This is a variant of the previous section for those of you who do not have write access to the CVS repository of a project and, therefore, cannot commit their modifications to the CVS reposi- tory. The variant explained here is actually a method that is universally used in the Open Source world to contribute source code modification to the project team. It consists in the generation of a text file containing the differences between your modified version of the source code and the original one that you initially downloaded. This file is called a diff file because there is a tool called diff that can automatically do that for you. The reason why diff files are so popular is because they follow a well-documented format. Diff files are sent to the original project team which, upon reception, is going to use another univer- sal tool called <litteral>patch</litteral> to automatically merge the contributed changes with the master copy of the source code. This is why, by extension, a diff file is also known as a patch. Diff files can be generated either with the <litteral>diff</litteral> tool (part of the GNU tools) that is available on all platforms including Windows or directly with CVS if you have been hacking on a CVS working copy. The <litteral>diff</litteral> way: • Use the diff way when you obtained the original source code from a File Release and not from the project CVS repository. Let's assume the original source file is under the di- rectory project-0.1/ and that your modified version is under project-0.1-new/ • You can generate a diff file with the following command (all files in subdirectories will be checked recursively for changes) diff -rc project-0.1/ project-0.1-new/ The CVS way: • This is the preferred way when you obtained the source code by creating your own CVS working copy. Let's assume that you are at the top level of the working copy. • You can generate a diff file between your version and the very latest version in the CVS repository for the entire source tree by typing with the following CVS command: cvs diff -c • If you want to generate a diff against a specific version of the source tree, then specify the tag for this version (version V1 in the example below) in the command line: cvs diff -c -r V1 In both cases, store the output of the diff or cvs diff command in a text file. Compress the output 117
  • Codendi User Guide file if it's a large one and use the Codendi Patch Tracker (see Section 7.12.2 [page 66]) to sub- mit your patch to the project team). And thanks for contributing some code! 9.4.7 Exporting and Packaging Audience: project members There is a quick and easy way to release a pre-packaged version of your source file and make it available to your users through the File Release mechanism (see Chapter 8 [page 96]). 1. Make sure all the project members involved in software development have committed the changes that were supposed to appear in this new release. 2. Update your own working copy with the changes committed by all other project mem- bers with the following command: cvs -q update 3. Update the ChangeLog, Release Notes and README file at the top of your source tree and commit the changes for these 3 files. 4. Tag (mark) the CVS repository with the appropriate version number. This version num- ber will be attached to the most recent revision of all committed files. From your work- ing copy type (V_1_2 is a tag name that represents version 1.2 of your project): cvs -q tag V_1_2 5. Your software release is now ready. Export a clean image of the CVS source tree in a fresh directory. By clean image we mean an image without any CVS specific files in it. Just source files. Assuming that you wish to export version 1.2 (tagged with label V_1_2) and that you want the exported software to be rooted under the project- name-1.2 directory, type: cvs -d:pserver:loginname@cvs.projectname.www.codendi.org:/cvsroot/projectnam export projectname-1.2 6. Create a ZIP or tar archive with the entire project-1.2/ directory 7. Deliver this archive through the File Release service (see Section 8.4 [page 99]). 8. Done! Nice job...Take a break. And remember to announce the availability of your new version via the Codendi News service (see Section 15.2 [page 171]). 9.5 CVS for Project Administrators There are a few things that Project Administrators must absolutely be aware of to manage their CVS repository well. 9.5.1 More on CVS Access Control As explained in Section 9.2.2 [page 108] CVS is setup in such a way that write access is granted to all project members (and project members only). It is, however, possible for a project administrator to deny CVS write access to certain project members. Revoking CVS write access for project members is not (yet!) feasible from the Web 118
  • Codendi User Guide interface. You must use your Shell Account to log into the Codendi server (see Section 18.1 [page 189]) and type the following commands at the shell prompt: • newgrp projectname (Where projectname is the short project name) • cd /cvsroot/projectname/CVSROOT • Edit the readers file and add the login name of the project members with read-access only (one login name per line) • exit (Logout) 9.5.2 CVS Administrative Files Each CVS repository comes with a number of administrative files that are all located in the CVS- ROOT directory. These files gives project administrators all sorts of interesting capabilities like the creation of virtual modules from a collection of files and directories, trigger e-mail notification on certain events like commit or add (note: Codendi already does it for you - see below), check the format of a CVS tag before accepting it, etc. (See the CVS Documentation cited in Section 9.1.2 [page 107] for more information about CVS administrative files). Tip: Never edit CVS Administrative files in place Never-ever edit any CVS administrative files directly in the CVS repository by using your Codendi Shell Account (except for readers and writers files). Always use CVS itself to manage the changes you want to apply to these files. Proceed as usual by checking out a working copy of the CVSROOT directory. Edit the appropriate files and commit the changes to the repository. When making changes to the administrative files make sure you preserve the Codendi specific settings in the following files: config, writers and loginfo. Also be very careful not to change directory or file ownership unless you know exactly what you are doing. 119
  • Codendi User Guide CHAPTER 10 Version Control with Subversion This chapter is not a Subversion Tutorial. It focuses on the integration of Subversion with Co- dendi and how to use it in an optimal way in this context. If you are not familiar with Subversion we warmly advise you to first read some of the documents listed in the references section (see Section 10.1.2 [page 122]). It is important to note that a version control tool like Subversion is just a part of the overall con- figuration management activity. Therefore, Subversion alone does not constitute a complete configuration management solution for your project. Depending on the maturity of a project, the project may have specific policies regarding the use of the software baseline or the integration of bug fixes, etc. The Subversion tool may allow you to enforce some of these mechanisms but project managers should make sure that these policies are documented, maintained and well understood by all project members. For example, a project may wish both to commit changes daily to avoid loss of work, and to also insure that the baseline is always unit tested code. Since the end of the day may arrive before the code or unit tests are complete, a single baseline cannot accommodate both uses, so the project may opt to use Subversion branches. Don't worry if you do not initially know enough to write the final configuration management policy for your project - this always tends to evolve as the project matures - but do communicate regularly with the project members and improve your configuration management plan on a regular basis. 10.1 Subversion: The Next Generation CVS Subversion is an Open Source version control system that manages your files and directories history over time. The Subversion effort started in early 2000 under the leadership of Karl Fogel, a recognized guru of CVS and author of the so-called 'CVS Black Book'(see Section 10.1.2 [page 122]). Like millions of developers in the world, Karl had used CVS for years and acknowl- edged the fact that, in spite of its merits, it had a number of shortfalls that would be nice to fix. From the very beginning the Subversion team, sponsored by the CollabNet company, clearly stated that the goal was not to produce a revolutionary version control system but rather to build on the strengths of CVS and wipe out all of its weaknesses. As a result, like CVS, Subversion belongs to the family of concurrent version control system. It means that a team of multiple de- velopers can concurrently manage their own version of the same source code and gracefully merge the changes brought to the software by the various team players. But Subversion also comes with a number of enhancements over CVS: • Directory versioning: because CVS relies on the native file system of the machine it runs on it has been impossible to implement the versioning of directories. Subversion 120
  • Codendi User Guide implements a "virtual" filesystem stored in a database that tracks changes to the entire directory and file tree. • True version history: moving and renaming files in a CVS repository has some limita- tions mainly due to the fact that versioning is attached to individual files. With Subver- sion you can add, delete, rename and copy files or entire directories without doing any compromise on the file naming or the file history. • Atomic commits: although Codendi provides an additional layer on top of CVS which gives an atomic view of the commits, CVS itself has no notion of the fact that you may have committed a dozen file at the same time to fix a single bug. Subversion on the con- trary stamps the entire tree with a new revision number each time you make a change. • Versioned metadata: Subversion can attach any number of properties (in the form of key/value pairs) to files and directories. Properties are themselves versioned like the files and directories they are attached to. • Various access protocols: Like CVS, Subversion offers a choice of network protocols to access a subversion repository. It can be a local file system access or a network ac- cess through the Subversion own's lightweight protocol (svnserve) or a secured remote access through SSH. Additionally and more importantly, Subversion can be accessed through the WebDAV protocol which is an extension of the HTTP protocol. This has a number of advantages like the ability to run all transactions through secure HTTP, go through firewalls and take advantage of the HTTP authentication methods. • Efficient diff'ing: when you create a working copy on your desktop machine, a com- plete version of the original file is kept on your disk which allows developers to perform status and diff operations even when working offline. • Efficient branching and tagging: in Subversion these 2 operations are performed by literally copying (all or part of) the repository. The copy is virtual in the sense that the vir- tual filesystem establishes hard links to indicate from which revision the copy comes from. As a result branching and tagging takes a very small amount of disk space and, above all, it takes a constant amount of time regardless of the repository size. • Fine grain access control: in its Codendi incarnation, your Subversion repository oper- ates on top of the HTTP (or HTTPS) protocol and it therefore take advantage of the rich HTTP authentication mechanism. As a result Codendi allows you to fine tune who has access to which part of your Subversion repository whether for read, write or no access at all. • Extensibility: like CVS, Subversion comes with a number of facility to hook custom pro- cessing at the various stage of a commit operation (pre-check, post-check,etc.). Unlike CVS, Subversion comes with well documented library APIs with bindings available for several languages like C/C++, Java, Python and Perl. 10.1.1 Subversion Clients Subversion has a client-server architecture. In other words, Codendi developers who want to in- teract with the Subversion repository of their project must have Subversion installed on their desktop machine, hereafter called client. The Codendi server permanently runs a Subversion server in the background to which Subversion clients talk to to act upon the Subversion reposi- tory. Subversion clients come in various flavors for all sorts of platforms (Windows and all Unix): 121
  • Codendi User Guide command line interface, graphical based interface and web based interface. Command Line Interface Subversion comes with a command line interface that can be used on virtually any platform (Linux/Unix, MS Windows, Mac...). Even though Subversion has multiple command line options, most commands that you normally use have one or two command-line options and are very easy to remember and look a lot like cvs commands. Refer to Section 10.1.2 [page 122] for more information about how to use the Subversion command line. Graphical Front-ends Subversion already has a number of graphical front-ends. rapidSVN is part of the standard Sub- version package and runs on Linux and Windows. TortoiseSVN is another option for MS Win- dows users. jSVN is a Java based client that can run on any platform. As time goes the list of graphical front-ends will certainly grow. Refer to Section 10.1.2 [page 122] for more information about those graphical clients. Setting up rapidSVN for Codendi As mentioned above, rapidSVN is the graphical user interface that comes with Subversion for Linux and Windows. Below are all the instructions needed to get rapidSVN running on a Co- dendi project. In the instructions below, "username" is the Codendi user login name, and "pro- jectname" is the Codendi short project name the user is working on. • Download rapidSVN from the Subversion Web site and install it on your PC. • Launch the rapidSVN application. • Create a new bookmark for your Subversion repository: Bookmarks->Add Reposi- tory... When prompted enter the URL to your repository: http://svn.projectname.www.codendi.org/svnroot/projectname • Click on the new bookmark corresponding to your repository and type you Codendi user name and password when asked to. You should now be able to browse the repository and see the file status and revision history. • To create your own working copy use the menu item Repository->Checkout... When the dialog box pops up, type the same URL as above and choose where you want your working copy to be created. • A second bookmark corresponding to the new working copy should now appear in the bookmark pane on the left hand side of the screen. On the right hand side appears the list of files and directories of your working copy along with their revision number and sta- tus. From there use your favorite editor to modify the source code, hit the refresh button in rapidSVN to see modified files and commit your changes when your are done. 10.1.2 Subversion References 122
  • Codendi User Guide As stated earlier in this chapter, this document is not a Subversion Tutorial. If you want to learn more about Subversion refer to the following documents: • The Subversion Book. See http://svnbook.red-bean.com). • The Official Subversion Web Site. See http://subversion.tigris.org/ This is where you'll find the subversion software including the rapidSVN client. • TortoiseSVN. A graphical MS Windows and Linux graphical client. See http://tortoisesvn.tigris.org/. • jSVN. A graphical 100% Java graphical client. See http://jsvn.alternatecomputing.com/. 10.2 Subversion Integration in Codendi 10.2.1 The Subversion Repository Whenever a new project is hosted on Codendi, a new Subversion repository is automatically created and properly initialized. Each project has its own Subversion repository as opposed to what happens in most Subversion servers, where several projects share the same repository. Having its own repository has a certain number of advantages: the Subversion logs, history files, and all administrative files (e.g. hook scripts) are unique to each project repository. This al- lows you to fully customize the behavior of Subversion for a given project without impacting the others. All interactions with a Subversion repository should normally happen through a Subversion client. However if need be and if this feature is available on your Codendi server, you can get access to your Subversion repository via your Codendi shell account (see Section 18.1 [page 189]). Once the shell session is active you'll find your subversion repository under / svnroot/projectname you should never do that unless you know exactly what you are do- ing. 10.2.2 The Subversion Repository Structure When a new Codendi project is created, it comes with a virgin subversion repository that the project team must populate. Due to the fact that Subversion manages branching and tagging through its virtual filesystem (and not through labels attached to individual files as in CVS) there is a recommended way to organize your repository. The layout suggested below can be consid- ered as a de-facto standard and we highly recommend that you follow this best practice. If you expect your Codendi project to manage only one project deliverable then you can create the following top-level directories in your repository: /trunk /branches /tags where /trunk contains the main line of development, /branches contains branch copies and /tags contains tag copies of your source code that generally correspond to a given release. If you expect your Codendi project to manage several software deliverables that are managed 123
  • Codendi User Guide independently one from each other, then it is often a good idea to first create top-level directo- ries that carry the name of the sub-project and under each of these directories repeat the same structure as above. Assuming you have two subprojects named engine and client, the initial layout of your repository should look like this: /engine/trunk /engine/branches /engine/tags /client/trunk /client/branches /client/tags More on the repository layout is available in the Subversion book listed in Section 10.1.2 [page 122]. 10.3 The Subversion Browsing Interface Codendi offers a number a facilities that allow you to interact with your Subversion repository through the Web interface. The Subversion Web interface does not intend to replace the Sub- version client that you should normally use on your desktop computer. It rather focuses on pro- viding you with additional features not found in Subversion clients. The Subversion Web interface can be accessed via the "Subversion" item in the Project Main Menu or via the Subversion service listed in the Public Area (see Figure 7 [page 23]). The Co- dendi Subversion Web interface provides the following features to Codendi end-users: • Accessing the Subversion repository: The welcome page of the Codendi Subversion service gives you all the information you need to access the Subversion repository from your Subversion client. Among other things it tells you what the Subversion root path is and how to checkout the source code. This page may also be customized to display project specific instructions (see Section 10.4 [page 127]). • Browsing the Subversion repository: this feature allows you to browse the Subver- sion repository even if you don't have a Subversion client installed on your desktop ma- chine. • Querying Subversion : If the Subversion tracking feature has been activated for your project all Subversion events (commit, file addition or deletion) are tracked down in the Codendi database. This audit trail can be searched using several criteria. • Subversion Administration : this service allows project administrator to perform the most common Subversion administration and configuration tasks from the Codendi Web interface (for more details see Section 10.4 [page 127]). Let's review some of these features in more details. 10.3.1 Browsing The Subversion Repository In order to interact with the Subversion repository of any Codendi-hosted project, you normally need to have Subversion installed on your machine. However Codendi also offers a built-in Web browsing interface to the Subversion repository which allows you to navigate in the source code, 124
  • Codendi User Guide download it, view a file history or compare two revisions of the same file. Figure 55. Browsing the Subversion repository - A sample session 10.3.2 Querying Subversion If a project has the Subversion Tracking feature activated (see Section 10.4 [page 127]), the Sub- version Web interface will bring very useful features to the software engineers: • Atomic Subversion commit and unique commit ID: all changes (file modification, ad- dition or removal) that are committed in one go from your Subversion client are as- signed a unique commit ID also known as a Subversion revision number. • Commit cross-referencing: the unique commit ID (or revision number) generated at each commit can be referenced in future commits, or in the follow-up comments of project artifacts like bugs/tasks/support requests simply by using the pattern commit #XXXX, or revision #XXXX or even rev #XXXX (where XXXX is the unique commit ID). Any reference of that kind will be automatically transformed into an hyperlink to the Subversion tracking database. This mechanism makes it very easy to go from project artifacts like bugs, support requests or tasks to source code changes and vice-versa (more on this mechanism at Section 10.3.3 [page 126]). • Commit search: another side benefit of the Subversion Tracking database is that you can use various search criteria to query the Subversion tracking database. You can search code changes by authors (who made the change), by revision number, by file path or by keywords to be found in the log message. Results can also be sorted by clicking on the headers of the search results (see Figure 56 [page 126]). A click on one of the selected commit ID brings you to a complete description of the change, the files that were impacted and the nature of the change with a direct link into the Subversion repository if you want to browse the file or look at the code modification (see Figure 57 [page 127]). 125
  • Codendi User Guide Figure 56. Querying the Subversion tracking database of a given project 10.3.3 Cross-Referencing Artifacts and Subversion Commits While working in the development or the maintenance phase of a software project, it is vital to keep track of the changes made to the source code. This is what Version Control systems like Subversion do. In addition to keeping track of the source code change history it is often critical to relate the changes to the artifact (a task, a defect or a support request) that led the develop- ers to make a change in the code. And conversely, when reading the artifact description it is also very helpful to immediately see how the change was implemented. The integration of Subversion in Codendi precisely provides Codendi users with this bi- directional cross-referencing mechanism. This is achieved through the use of reference patterns that are automatically detected by Codendi in either the follow-up comments of the project arti- facts or in the messages attached to a Subversion commit. The text patterns to type in a commit message or a follow-up comment are as follows: • XXX #NNN: this pattern refers to the artifact XXX number NNN, where NNN is the unique artifact ID, and XXX is the tracker short name (e.g. "bug #123", "task #321", "req #12", etc.). If you don't know the tracker short name or don't want to specify it, you may simply use "art #NNN". When browsing a message containing this pattern anywhere in Codendi, the pattern will be automatically transformed into an hyperlink to the artifact 126
  • Codendi User Guide description. • revision #YYY or rev #YYY: this pattern refers to the commit YYY where YYY is the commit revision number. When browsing a message containing this pattern anywhere in Codendi, the pattern will be automatically transformed into an hyperlink to the commit description which include log messages, impacted files, versions and author of the change(see Figure 57 [page 127]) . • The Codendi reference mechanism allows cross-referencing with any Codendi object: artifacts, documents, files, etc. Please refer to Section 6.8.1 [page 30] for more details on Codendi references. Figure 57. The detail of an atomic Subversion commit Tip: cross-reference artifacts and Subversion commits It is considered a best practice to always reference a bug, a task or a support request in any of the log message attached to a Subversion commit. Similarly when closing the related artifact (task, bug,etc.) make sure you mention the revision number in the follow-up comment. You will find this ex- tremely convenient while trying to keep track of the changes and why they were made. 10.4 Subversion Administration Interface Through the Codendi Web interface, project administrators can perform the most common ad- ministration and configuration tasks on their Subversion repository. The administration functions can be accessed through the SVN Admin menu item in the Subversion menu bar. 10.4.1 General Settings • Subversion Tracking: Being a version control system Subversion is, of course, natively 127
  • Codendi User Guide taking care of all your file history and is able to tell you what changes were made by whom and at what date. The file history is something you can look at either through your Subversion client or through the Subversion Web Browsing interface. If you activate the Subversion tracking (default) for your project Codendi will also keep track of all the code changes in the Codendi database. This will give you extra capabili- ties on your Subversion repository as explained in Section 10.3.2 [page 125]. • Subversion Preamble: In some cases (e.g. when your project already has its own sub- version server in place), the project Subversion repository might not be hosted by the Codendi server. In this case, the Subversion information displayed in the welcome page of the Codendi Subversion service are inadequate. Fortunately, the project administrator can customize the Subversion Information page here. 10.4.2 Subversion Access Control Default Access Permissions Subversion access permission depends upon the project status (private or public) and the class of citizen a user belongs to (see Section 3.1 [page 13]). Regarding private projects, only project members have access to the Subversion repository. By default they all have read and write access. This can be modified by customizing access per- missions as explained below. With respect to the public projects, the default access permissions are as follows: • Anonymous Users: users who have not registered with Codendi (or are not logged in) have no access at all to the Subversion repositories. • Registered Users: have read-only access to Subversion repositories. In other words they can checkout a working copy of the software but they are not allowed to commit any changes they have made to the source code. Source code contributions (bug fix, enhancements…) from this class of user must return to the project team via the Patch Tracker (see Section 7.12.2 [page 66] ). Note: if the "restricted users" mode is on (See Section 3.1 [page 13]), then there is no access for non project members by default. Note: all source code accesses are recorded by Codendi. Project administrators always have access to the list of people who accessed the source code (see Section 6.14 [page 42]). • Project Members: members of a Codendi hosted project are granted a password pro- tected read/write access. As mentioned above in the section about private projects, it is also possible to grant read-only access to the project members. • Project Administrators: same as project members. Customized Access Permissions Thanks to the integration of Subversion in the Codendi environment, project administrators can 128
  • Codendi User Guide redefine access permissions for some or all Codendi users. This can be achieved by specifying access permission rules that will complement or even over- ride the default settings. The syntax of the access permission rules follows the following pattern: [path] name = permission where: • path is the path to the directory or to the filename (relative to /svn- root/projectname) in your repository for which you want to redefine access permis- sions. • name is either a Codendi login name or group name. The name * (star) means any reg- istered user. If it is a group name it must be preceded with the @ character. The line name = per- mission can be repeated as many times as necessary for a given path. To define groups of users use the following block statement: [groups] groupname = username1,username2,... All project defined user groups (see Section 6.10 [page 35]) are also defined in the Co- dendi default permissions settings and ready to use if you wish to redefine access per- missions. • permission is either r for read-only access, rw for read-write access or blank if ac- cess is forbidden. As an illustration, the default permission settings of a Codendi repository as explained in the previous section are expressed through the following set of rules: [groups] members = member1,member2,...,memberN [/] * = r @members = rw where member1,member2,...,memberN are the Codendi login name of the Codendi project members. Additionally, all existing user groups defined in this project are listed in this section. These default permission settings are automatically generated, and cannot be edited. You should consider this section as the beginning of the Subversion permission file: project adminis- trators can then edit additional permissions that will be added below the automatic section. Please note that it is not possible to restrict permissions already granted on the same directory. 129
  • Codendi User Guide For instance, a public project has the default permission file detailed above; it is useless to add a stricter rule on the root directory. For instance, adding: [/] * = will not prevent registered users to access the repository, since the default rule already grants this permission. However, it is possible to restrict permissions on a subfolder: [/secret] * = @members = rw will indeed prevent registered users from reading the '/secret' directory. If you really need to prevent access to the whole repository, you should contact a Codendi ad- ministrator. For more information about the format of this file you should refer to the Subversion Book (see Section 10.1.2 [page 122]). 10.4.3 Subversion Email Notification In addition to tracking the changes in the Codendi database, Codendi can also send a nicely for- matted email message to individual email addresses or mailing lists each time there is a change in the source code. The email message contains the log message, the author of the change, the list of impacted files and pointers to the Subversion repository showing what changes were made. Project Administrators can configure the following settings for email notification: • Email addresses: a comma separated list of email addresses of people to whom the email notification must be sent can be given. If you want to notify a large group of peo- ple then we strongly advise you to create a mailing list first (see below). • Subject Header: is a piece of text that will appear as a trailer in the Subject of all the email notifications sent to the addressees. This trailer is supposed to help the ad- dressee to quickly spot the messages in their Inbox or to put filters in place to route the email notification to a given folder. Tip: create a specific mailing list for Subversion events notification If you intend to generate email notification for the changes made in your Subversion repository, it is a good practice to create a specific mailing list called projectname-svnevents. By doing so, Co- dendi users and project members interested in receiving the email notification just need to subscribe to the mailing list. In addition, the Codendi mailing list manager will archive all the email messages which can prove very useful for future reference. See Section 15.1 [page 170] for mailing list creation. 10.5 A Typical Subversion Life Cycle 130
  • Codendi User Guide As stated earlier, the intent of this chapter is not to give a formal Subversion training but rather to explain what are the steps a project team typically goes through when using Subversion and, more generally, all the Codendi tools involved in a Software release process. It also deals with the problem of contributing source code when you are not part of a project team. In this section all examples are given in the form of Subversion command lines but trans- posing them to graphical front-ends should be relatively straightforward. Figure 58. A Typical Software Development Life Cycle on Codendi 10.5.1 Logging In Audience: all Codendi users Unlike CVS when used with the pserver protocol there is no explicit login command to issue to start working with a Subversion repository. Subversion will ask for your login name and pass- word only when performing an operation (e.g. commit) that requires authentication. 10.5.2 Importing Existing Source Code Audience: project members As the happy administrator of a new Codendi project, the first thing to do is to populate your freshly brewed Subversion repository with your project source code. To do so, first create a new directory topdirectory on your workstation and populate this top level directory with the rec- ommended directory layout documented earlier (see Section 10.2.2 [page 123]). Place yourself into the topdirectory and type the following command (in one line): 131
  • Codendi User Guide svn --username loginname import . http://svn.projectname.www.codendi.org/svnroot/projectname --message "Initial repository version" Where: • projectname is the project short name • loginname is your Codendi login (all lowercase). The --username option is only needed if your Codendi login name is different from the Unix or Windows login name you are currently working with. If your Subversion server is configured in secure mode, note that you should use https://www.codendi.org/svnroot/projectname instead of http://svn.projectname.www.codendi.org/svnroot/projectname in all the exam- ples given on these pages. Tip: made a mistake while importing your source code? It is not unusual to make a mistake when importing your source code into a fresh Subversion reposi- tory especially for new users. Typical mistakes are directories placed at the wrong level or with the wrong name. Nothing to fear though... If you want to start again from a fresh Subversion repository contact the Codendi Team to get your Subversion repository reinitialized. Alternatively you can easily delete or move directories and files with any subversion client afterwards. Note that if you already have a Subversion repository available, the Codendi Team can help you migrate this repository on Codendi and preserve all of your project history. We just need a dump of your Subversion tree generated with the svnadmin dump command. With this dump the Co- dendi Team will re-install everything for you on the Codendi server. Contact us for more infor- mation. 10.5.3 Checking Code Out Audience: all Codendi users Once a Subversion repository has been populated other Codendi users can checkout the source code and place it on their own workstation. The result is called a working copy in the Subversion jargon. Note that 'checkout' in the Subversion world does not mean that the user has acquired any sort of lock on the file. The Subversion paradigm is: anyone (with the right per- missions) can retrieve a working copy for editing; changes are reconciled or flagged for conflict resolution when the file is committed. Unlike other tools (RCS, SCCS, ClearCase...) Subversion is a concurrent version control system. A working copy is NOT an image of the Subversion repository. It is rather a snapshot of the source tree at some point in time and, by default, it's the latest version at the time the working copy is created or updated. One of the interesting features of a working copy is that it is a self- contained entity. In other words, a working copy contains all the necessary information for Sub- version to know exactly which Subversion server and repository it is coming from and the corre- sponding moment in the history of the source tree . This is also why you won't see the URL op- tion pointing to the Subversion repository in all subsequent Subversion commands presented here. These commands run from within a working copy, so Subversion knows exactly where the Subversion repository is. 132
  • Codendi User Guide To create a working copy of the entire project type the following command: svn checkout http://svn.projectname.www.codendi.org/svnroot/projectname Where: • projectname is the project short name 10.5.4 Updating the Source Code Audience: all Codendi users Running an update command from within a working copy has the effect of updating the working copy (or a subpart of it) with the latest version of each source file from the repository. To update a working copy type: svn update 10.5.5 Examining your Changes If you want to know which files have been modified in your own working copy since your last up- date, run the following command: svn status Or wich files have changed on the Subversion repository since your last update : svn status -u The output will show you a list of files which undergo some changes either because they were modified, added or deleted. To compare your locally modified version of a file with the original version in the Subversion repository, you can use the diff command: svn diff filename If no filename is specified the diff operation is applied recursively on all the files and sub- directories. 10.5.6 Committing your Changes (project team) Audience: project members Project members involved in development activities will likely want to contribute the changes made in their own working copy back to the Subversion repository. In Subversion terminology this is called a commit operation. To commit changes you have made in your working copy, type the following command: 133
  • Codendi User Guide svn commit -m"Explain the nature of the change here..." filenames Where: • The -m option is followed by a text message explaining what changes you have made. • The filenames argument is optional. It can be individual files or directories. If there isn't any files mentioned Subversion will automatically commit all the modified files in the di- rectory where you are located and all sub-directories recursively. Tip: Include a bug or task number in your commit messages In the ideal world, all modifications made to the source code of a project should be related to either a bug logged or to a task assign to a developer. If your project team lives in this wonderful world :-) then don't forget to include the related bug or task ID number at the beginning or at the end of your commit message. The Subversion hook scripts can help you enforce this rule by checking the format of all the submitted commit messages and reject them if it does not follow the recommended pattern. Tip: update before you commit If you try to commit a modified file that was also modified on the Subversion repository in the mean- time, the Subversion server will refuse to execute the svn commit command. You must first exe- cute a svn update command to bring your own working copy up to date with latest version, merge your changes with those from others (Subversion does it automatically in most cases) and then only commit your own changes back to the Subversion repository. If you want to be immune from others' changes then create a Subversion branch and work with it in isolation. 10.5.7 Contributing your Changes (other users) Audience: all Codendi users This is a variant of the previous section for those of you who do not have write access to the Subversion repository of a project and, therefore, cannot commit their modifications to the Sub- version repository. The variant explained here is actually a method that is universally used in the Open Source world to contribute source code modification to the project team. It consists in the generation of a text file containing the differences between your modified version of the source code and the original one that you initially checked out. This file is often referred to as "diff file". The reason why diff files are so popular is because they follow a well-documented format. Diff files are sent to the original project team which, upon reception, is going to use another univer- sal tool called patch to automatically merge the contributed changes with the master copy of the source code. This is why, by extension, a diff file is also often referred to as a patch. Diff files can be generated either with the diff tool (part of the GNU tools) that is available on all platforms including Windows or directly from within a Subversion working copy. The Diff way: • Use the diff way when you obtained the original source code from a File Release and not from the project Subversion repository. Let's assume the original source file is under 134
  • Codendi User Guide the directory project-0.1/ and that your modified version is under project- 0.1-new/ • You can generate a diff file with the following command (all files in subdirectories will be checked recursively for changes) diff -rc project-0.1/ project-0.1-new/ The Subversion way: • This is the preferred way when you obtained the source code by creating your own Sub- version working copy. Let's assume that you are at the top level of the working copy. • You can generate a diff file between your version and the very latest version in the Sub- version repository for the entire source tree by typing with the following Subversion com- mand: svn diff • If you want to generate a diff against a specific version of the source tree, then specify the revision number in the command line (revision #9398 in the example below): svn diff -r 9398 In both cases, you should redirect the output of the diff or svn diff command in a text file. Com- press the output file if it's a large one and use the Codendi Patch Tracker (see Section 7.12.2 [page 66]) to submit your patch to the project team. And thanks for contributing some code! 10.5.8 Exporting and Packaging Audience: project members There is a quick and easy way to release a pre-packaged version of your source file and make it available to all Codendi users through the File Release mechanism (see Chapter 8 [page 96]). 1. Make sure all the project members involved in software development have committed the changes that were supposed to appear in this new release. 2. Update your own working copy with the changes committed by all other project mem- bers with the following command: svn update 3. Update the ChangeLog, Release Notes and README file at the top of your source tree and commit the changes for these 3 files. 4. Create a tagged copy of your source code from the main development line with the ap- propriate version number. Assuming that the name of the release is myproject-1.4 the creation of the new release is as follows: svn copy http://svn.projectname.www.codendi.org/svnroot/projectname/trunk http://svn.projectname.www.codendi.org/svnroot/projectname/tags/myproject-1. -m "Tagging the 1.4 release" 135
  • Codendi User Guide 5. Your software release is now ready. Export a clean image of the release 1.4 (without Subversion specific files) from the Subversion repository by typing: svn export http://svn.projectname.www.codendi.org/svnroot/projectname/tags/myproject-1. 6. Create a ZIP or tar archive with the entire myproject-1.4/ directory 7. Deliver this archive through the File Release service (see Section 8.4 [page 99]). 8. Done! Nice job...Take a break. And remember to announce the availability of your new version via the Codendi News service (see Section 15.2 [page 171]). 10.6 Subversion for Project Administrators 10.6.1 Subversion Hook Scripts Codendi offers an easy to use Web interface to administrate the common settings of your Sub- version repository like access control and email notification. In case project administrators want to go deeper in customizing the behavior of their Codendi repository, they can get access to the Subversion hook scripts. In order to access those hook scripts, you must be granted the right to log into the Codendi server with your Shell Account (see Section 18.1 [page 189]) 6. . Once logged in, type the following commands at the shell prompt: • newgrp projectname (where projectname is the short project name) • cd /svnroot/projectname/hooks • If the hook scripts you want to customize does not yet exist in the hooks directory, first create them by copying the corresponding template file provided by Subversion (.tmpl extension). Then edit the hook scripts in place. • exit (Logout) ***Important Note***: Mind the Codendi Hooks! If you decide to customize the Subversion hook scripts for your repository make sure to preserve the statements that could have been inserted by Codendi in the first place. The Codendi statements are clearly marked with a recognizable header and trailer. 6The Shell Account may have been deactivated by your Codendi site administrators. 136
  • Codendi User Guide CHAPTER 11 Document Manager Documentation is probably the second most important deliverable in a software project after the software work products themselves. Codendi provides a specific service to manage your project documents. Although the Codendi Document Manager cannot be compared with dedicated document man- agement systems, it is however very handy to publish documents that are critical to your com- munity of users. Examples are: Installation, Administration or User Guide, API documentation, Frequently Asked Questions, etc... The Document Manager features are as follows: • The Codendi Document Manager can handle any type of document. • Documents are stored in folders. You can have subfolders in a folder. • Documents can be edited on line (if in text or HTML format). • Access control rules can be defined for each document or folder. • Documents have properties and searchable metadata. 11.1 Structure You can structure as you want your document manager by creating folders and subfolders to classify your documents. Figure 59. Folders and subfolders 137
  • Codendi User Guide 11.2 Actions The Document Manager allows some actions on folders or documents. Those actions are avail- able or not depending on permissions. In order to display the action panel, you must click on the pencil icon next to the document or folder name. Figure 60. Actions We will now describe all the actions that can be performed on a folder or document. 11.2.1 New Document This action is only available for folders and allow the user to create a new document in a folder. When you select this action, a "new document" window is displayed, where you can enter infor- mation concerning the new document. 138
  • Codendi User Guide Figure 61. Create a new document The new document inherits the permissions of the parent folder. Metadata The title of the document is mandatory. The user can provide a description which will be dis- played on the browse view. Depending on the project, there may be additional metadata re- quired to classify the document. 139
  • Codendi User Guide Document Type 5 types of documents are available : • Empty: the document will have no type. The user will be able to change the type after creation. • Link: allow the user to target a document with a URL. The document will not be stored locally in the docman. • Wiki: the document could be created with the wiki service. Just enter the name of the corresponding wiki page. You can also use an existing wiki page name. • File: any type of document could be uploaded. From a PowerPoint presentation, to a simple picture or a full office document. Files are versionned, so you can add new ver- sions on existing document. • Embedded file: html or plain text can be edited online. Embedded files are versionned. Location By default, the system creates a document in the folder that was selected. The user can also choose another folder. He can also select the position of the new document in the folder: at the beginning or at the end. 11.2.2 New Folder This action is only available for folders and allow the user to create a sub folder in a folder. 140
  • Codendi User Guide Figure 62. Create a new folder The new folder inherits the permissions of the parent folder. Properties Like for documents, the title of the folder is mandatory. The user can provide a description which will be displayed on the browse view. Depending on the project, there may be additional proper- ties required to classify the document. Location Like for documents, by default, the system creates a folder in the folder that was selected. The user can choose another folder. He can also select the position of the new folder in the parent folder: at the beginning or at the end. 11.2.3 Properties This action allows the user to view the properties of a document or folder. If he has enough per- 141
  • Codendi User Guide missions, he will be able to modify those properties. Figure 63. Display and edit properties From the property panel, it is possible to view/edit permissions, history and actions. There are also shortcuts to these panels in the initial "Actions" window. 11.2.4 Notifications This action allows the user to be notified when an item is modified. Therefore, he will be alerted about the creation of a document in a folder, about the update of a document, about its move, ... He just has to check the dedicated checkbox. Figure 64. Notifications 11.2.5 History This action allows the user to see logs and old versions (if available). 142
  • Codendi User Guide Figure 65. See a document history 11.2.6 Update This action allows the user to update the name of a wiki page or the url of a link. Figure 66. Update a link 11.2.7 New version This action allows the user to update a new version of a file or an embedded file. 143
  • Codendi User Guide Figure 67. Create a new version for embedded file 11.2.8 Permissions This action allows the user to manage the permissions of a document or folder. Permissions for folders can be applied recursively to its hierarchy. 144
  • Codendi User Guide Figure 68. Define permissions There is 3 types of permissions. Readers Those who can "read" a document or access the content of a folder. "read" means access to the document, see it in the browse view, see its properties or metadata, see its history. Please note that if a user cannot read a folder, then he cannot access to any of its subitems whatever their permissions, even deep in the hierarchy. Writers Writers are readers who can also modify the document. "Modify" means update a new version, modify the link or the wiki page name, edit properties, move the item or delete it. Managers Managers are writers who can also set permissions on a document or folder and can access to logs. 11.2.9 Move Documents or folders can be moved elsewhere in the project documentation. They can only be moved in a folder where you have write permissions. You can move an item in different ways. The traditional way is to select move from the popup menu. You will be able to choose the tar- 145
  • Codendi User Guide get folder (or let it in the same folder) and the new position (at the beginning, at the end or at a specific position). The permissions of the item will not be changed. Figure 69. Move a document If you just want to reorder a folder and move some of its items relatively to each other, you can click on shortcuts next to "move" item in the popup menu : up, down, at the beginning or at the end. Figure 70. Shortcuts to move a document inside a folder 11.2.10 Delete Documents or folders can be deleted. If the user wants to delete a folder, he will be warned that all subitems will be deleted (if the user has enough permissions). To be able to delete an item, the user must have write permissions on the parent folder. 11.3 Administration 146
  • Codendi User Guide 11.3.1 Permissions This section defines who can administrate the document manager. Document manager administrators have all access to all items of the manager. 11.3.2 Display preferences This section allows you to define the default view for the document manager. The settings will be overridden by user preferences. 11.3.3 Properties This section manage the properties of documents. Each property can be edited during docu- ment submission and updated in the document properties panel. There is no specific permissions. If a user can read(modify) a document, he can read(modify) all of its properties. 147
  • Codendi User Guide CHAPTER 12 Test Manager Testing is an important task in the project lifecycle. Codendi provides a specific service to man- age your tests. The test manager used in Codendi is SalomeTMF, a well known open-source Test Management Framework. For an extensive presentation of SalomeTMF, please visit the SalomeTMF project web page : https://wiki.objectweb.org/salome-tmf/ and in particular the documentation section. 12.1 Salome Overview The Test Manager features are as follows: • Tests creation. Tests can be organized in campaign, family, suite, following ISO 9646 norm. • Tests execution. Tests can be associated with environments, actions, executions, and dataset. • Tests can be executed manually or can be automated (with SalomeTMF plugins.) • SalomeTMF is integrated in Codendi, which means that you don't need to create your projects in SalomeTMF. Your Codendi projects will be automatically available in Sa- lomeTMF, as well as the project members. • The integration with Codendi also implies that you can add a bug in a Codendi tracker after a test execution failure. 12.2 Configuration and Administration 12.2.1 Salome Bug Tracker Salome can interact with Codendi trackers. The usual way of using Salome is to add bugs in the dedicated Salome bug tracker when a test fails. But you can use Salome with any tracker you want. You only need to add and/or link some "special" fields required by Salome. • environment • campaign • family • suite • test • action 148
  • Codendi User Guide • execution • dataset All these fields must be text fields. If you want to use Salome with one of your existing tracker, you have two options: • You already have fields that could match the Salome "special" fields, then see below "Salome tracker configuration" to link your fields to Salome, • Your tracker's fields don't match the Salome "special" fields, or you don't want to use your existing fields for this usage: then, you just have to create new fields of type "text field" ( see Section [page 75] for details), and then see below to link them to Salome. If you want to use a new tracker for Salome interaction, you can use the "Salome Bug" Tracker template, or create a new tracker using the Salome Bug Tracker template (see Section 7.11 [page 64] for details about creating trackers using templates) Salome tracker configuration To launch and use SalomeTMF with Codendi, you need to indicate which tracker you want to use with Salome. To do that, please select the Administration link of the Test Manager service, and select the link "Manage Tracker for Salome". Then, 1. select the tracker you want to use with Salome. It will refresh the other fields. 2. Select the report you want to use with Salome (this report will be used in Salome to browse and search the artifacts of your tracker). 3. Then associate each Salome "special field" with one of your tracker's field. 4. Then click on Submit button. Figure 71. Salome tracker configuration 149
  • Codendi User Guide If you make a mistake, you will be noticed about it, e.g. if you used twice the same field, or didn't assign a field. 12.2.2 Permissions SalomeTMF permissions can be set in the Codendi Test Manager Administration (Administration -> Permissions). Project administrators can configure permissions for project members, project administrators, and for every other user group defined in the project. The available permissions are : • Test Suite: • Add: if the user can add a test suite or not. • Modify: if a user can modify a test suite or not. • Delete: if a user can delete a test suite or not. • Test Campaign: • Add: if the user can add a test campaign or not. • Modify: if a user can modify a test campaign or not. • Delete: if a user can delete a test campaign or not. • Execute: if a user can execute a test campaign or not. Please note that there are dependencies between permissions (e.g. if you can add a test suite, you are also allowed to modify a suite). 150
  • Codendi User Guide Figure 72. Salome permissions configuration 12.2.3 Salome plug-ins SalomeTMF can be extended with plug-ins. Project administrators can choose the plug-ins loaded in Salome for this project. To select the plug-ins to use in your project, select the link Your Project -> Test Manager -> Ad- ministration -> Manage Salome Plugins, check the plugins you want, and then validate the but- ton. Please note that some Salome plugins may not be available depending on the server installa- tion 151
  • Codendi User Guide Figure 73. Salome plug-ins configuration 12.2.4 Salome Preferences Project administrators can select some Salome preferences for each project. Select Your project -> Test Manager -> Administration -> Manage Salome Configuration, Then select the options: • Include ICAL options: ICAL is a quality indicator, developed by Orange Labs. If you don't use this indicator for your project, you don't need to activate it. • Lock test plan if a campaign is being executed: check this option if you want the test plan to be locked once a campaign has been executed. • Lock test modification if the test has been executed: check this option if you want your test to be locked once it has been executed. Note: this implies that you can not replay a test. 152
  • Codendi User Guide Figure 74. Salome preferences configuration 12.3 Launching SalomeTMF Once your project is well configured (see Section 12.2.1 [page 148] for details) you can launch the SalomeTMF application by pressing the "Launch Salome" button. Figure 75. Launch Salome When clicking on the button, the system may ask you if you want to open with javaws (Java Web Start), answer "yes". Make sure you also accept all the certificates. Java Web Start may also ask if you want to create a desktop shortcut: answer "no", because Salome needs to be run always from Codendi (because it uses your Codendi session). SalomeTMF is then launched. 153
  • Codendi User Guide CHAPTER 13 Continuous Integration With Hudson 13.1 Introduction to Continuous Integration Continuous Integration is the given name for the good practices used in software engineering. These good practices aim at checking that a source code modification does not lead to a re- gression on the developping software application. This checking is usually performed on a dif- ferent machine than your development one (this machine is called an integration server); and this checking is carried out rather frequently 7, and so it's called Continuous Integration. The tool responsible for this checking is a Continuous Integration tool such as CruiseControl or Hudson. This checking is called a Build. A build will correspond, according to your project, in a succession of steps, such as: • Compilation, • Documentation generation (javadoc for instance), • Unit tests execution, • Quality analysis on source code (coding conventions, number of comments, code met- rics, etc.), • Delivery generation (exe, zip, tar, etc.). The continuous integration tool does not perform the build itself, but just launch it with regular in- terval, display the result of the build, and is able of sending notification to project members if a modification involved any regression. This development method, initiated at the beginning by the Extreme Programming community and adopted by Agiles methods, brings adding value to your development process. For in- stance: • Tests are immediatly executed after each modification (step sometimes neglected by developers), • Integration issues are continuously detected, to be fixed as soon as possible, • It always exists an operational version of deliveries available for tests, demo or distribu- tion. The continuous integration tool we decided to integrate in Codendi is Hudson, which is one of 7 Several strategies are possible: after each commit, with regular interval (every hours, every night). It depends on the size of the project, the number of developers, the frequency of modifications. 154
  • Codendi User Guide the actual best tool . Hudson configuration can be easily done on the web interface, and there is a contextual help for each step of the configuration, which is really appreciable. The lexicon of Continuous integration and Hudson is quite specific. Let's then give a definition: Word Definition Job The concept of Job can be associated with the concept of project. The job will trigger the build, but it's also in charge of setting the building environment required for execut- ing the build (updating the source code for instance). It will also be able to execute the build, and then perform some tasks such as publishing generated documentation, pub- lishing test results, sending notifications, etc.) Build Process is made of several steps executed periodically on a continuous integration server. Artifact Item are generated during the build, and are published by the continuous integration tool. The continuous integration notion of artifact is obviously different than the notion of a Codendi artifact (which is an item tracked in a tracker). Workspace Directory where the project will be deployed in order to perform the build, and enventu- ally publish artifacts. Status (of the build) Build status can take several values regarding the tool. Hudson has 4 status: • Successfull : everything went fine, all tests were successfull, • Unstable : the build was successfull but unstable (failed tests for instance), • Failed : the build fatally failed • Disabled : the project has never been built before, or the project is disabled. Trend (of the builds) Trend based on the latest 5 builds. This trend is represented by a weather report (sun, thunder, etc.) meaning that the trend is good or not. Table 2. Glossary of Hudson and continuous integration specific words 13.2 Hudson Installation A JVM (1.5 or higher) is required for Hudson installation. Hudson can be run standalone, but we will describe the installation in a container, such as Tomcat. Procedure 13.1. Here are the steps: 1. Install Tomcat 2. Download the Hudson war file (hudson.war) at https://hudson.dev.java.net/ 3. Set the environment variable HOME_HUDSON if you want to define the install folder of Hudson 4. Deploy the war file in Tomcat manager. You're done! Hudson is installed. By default, you can access the interface at http://localhost:8080/hudson 13.3 Hudson Configuration Before creating your own jobs, (see Section 13.4 [page 157]), you need to configure Hudson. All these steps are optional, you only have to configure what you really need. 13.3.1 System Configuration 155
  • Codendi User Guide To configure Hudson, select the link "Manage Hudson" in the top menu in Hudson interface, and then the link "Configure System". All these steps have an online contextual help. Don't be afraid to use it. To do it, you only have to select the question mark corresponding to the option needed. External Tools In order to be able to execute builds of your projects, Hudson needs to know the path to the tools required to. You can specify here the path to the external tools you need. By default, the available tools are JDK, Shell, Ant, Maven and CVS. If you install some plug-ins (see Section 13.3.2 [page 157]) that need external tools, you will be able to configure them in this section. Figure 76. External Tools Configuration You can define several instances of the same tool (several version of JDK for instance). Authentication By default, everyone can browse Hudson, browse the jobs, see the builds results and schedule builds on the web interface. You can nevertheless restrict the permissions. To do that, yo need to check the box "Enable se- curity" (still in the menu "Manage Hudson" -> "Configure System"). You have several options: • Delegate to servlet container: in our case, it means Tomcat. The Tomcat configuration file for user definition and permissions is <tomcat>/conf/tomcat-users.xml. See container documentation for more details. 156
  • Codendi User Guide • LDAP: if you already have a LDAP directory, you only need to specify the address of the server, and Hudson will recognize the users. • Hudson's own user database: Hudson can manage its own user database. In this case, you have to create yourself the users, or allow them to register. The choice of enabling security or not will depend on your company internal rules, or the speci- ficity of your projects or the size of the teams. Email Notification Hudson is able to send notification to warn about build result. You can of course configure this for each job. To enable notification, you need to state a mail server (SMTP server). Leave the field empty if you want to use the default mail server (localhost). You can also define a default user email suffix. By default, all of the Codendi users have an email address of the form login@www.codendi.org that is mapped to the real email address. You can then fill this field with the value @www.codendi.org and the emails will be automati- cally sent to the right users. You can also specify the system Admin Email Address. Notification e-mails from Hudson to project owners will be sent with this address in the from header. You finally need to state the URL of the Hudson server. URL in sent emails will then be correct. Jabber Notification If you have installed the Jabber plug-in for Hudson (see Section 13.3.2 [page 157]), you will find in the section "Manage Hudson" -> "Configure System" a part to configure Jabber notification. If the Jabber plugin for Codendi is installed and enabled, every Codendi user has a Jabber ac- count (see Section 15.4 [page 172]) and each project has a Chat Room. Jabber plug-in lets you the ability to send notification to users or chat rooms. To use the Jabber notification, please give the name of the server (by default www.codendi.org) as well as the JabberID of the user that will send the notifications. 13.3.2 Hudson Plug-ins Lots of plug-ins are available to extend Hudson. Among them, we can quote: checkstyle, CI game, Crap4J, LDAP Email, MSBuild, NAnt, NUnit, Selenium, etc. You will find a detailed list of all these plug-ins at http://hudson.gotdns.com/wiki/display/HUDSON/Plugins The list of available plug-ins is also available in the menu "Manage Hudson" -> "Manage plug- ins". The list is dynamicaly updated. If your continuous integration server is behind a proxy, you will need to configure it in the "Advanced" tab. To install a plug-in, check the box in front of the wished plug-in, press the Install button and then follow the instructions. 13.4 Hudson Jobs Creation and Configuration Once the system is configured, you can start defining your jobs. To do that, select the link "New 157
  • Codendi User Guide job" in the menu on top left. You just have to give a name (the name of your project for instance) and choose the type. Several types of jobs are possible. The most common is "free style soft- ware project" that we are using as an example in this documentation. There is also a type "Maven2" if you already use this build tool. Select the Ok button to confirm the job creation. The next screen is then the job configuration screen. You can add a description if you want. Then, you will be able to specify the source code repository, and the way that Hudson will handle the source code updates, define the steps of the build, and tell Hudson what to do after the build. 13.4.1 CVS and Subversion By default, Hudson suggests the same two SCM (Source Code Management) as Codendi: CVS and Subversion. Select the manager you're using for your project, and then enter the informa- tion about the paths to your project's repository. CVS To configure CVS, you need to give the CVSROOT of your project. The expecting format is :protocol:user@host:path You can find the details of the expecting string selecting the CVS tab of your project in Codendi. It looks like :pserver:[username]@[projectname].www.codendi.org:/cvsroot/[projectname] You can also provide one or several modules and/or a branch. Subversion To configure Subversion, you need to provide the URL of the repository. This piece of informa- tion is available on the Codendi interface, by selecting the SVN tab of your project. It looks like http://www.codendi.org/svnroot/[projectname] Hudson will then ask you to give credentials for Subversion, to be able to access the repository. You can then choose several options for managing this authentication (either give your login/ password or use SSH public key authentication or HTTPS client certificate). We let you choos- ing what option better fits your needs. You can add several repositories by pressing the button "Add more locations...". Finally, if you want to give the ability to the users to navigate in the source code repository through Hudson interface, you can select "ViewSVN" in the field "Repository browser", and then enter the folowing string: http://www.codendi.org/svn/viewvc.php?roottype=svn&root=[your_projet_short_name] 13.4.2 Builds Schedule As explained in introduction, the big thing with continuous integration is the fact that once con- figured, the build is continuously done, and you don't have to think about it. However, we still need to configure the way hudson will schedule the build. Two main options are available: • Poll SCM: will poll changes in your project SCM (CVS or Subversion). You can define 158
  • Codendi User Guide the frequency following the cron syntax (see Hudson inline help). This option can how- ever be expensive operations for the Codendi server. You can think of using the 'push' option to avoid this problem (see below). • Trigger builds remotely: this 'push' option avoids server overloading. The build is trig- gered by an URL. To avoid anybody to trigger builds, you can protect the operation by specifying an authentication token. To really enable the build trigger after each commit, you will need to configure it in Codendi, in the 'Build' tab of your project (See Section [page 160]). You will be able to specify your token if you have defined one. 13.4.3 Build configuration (steps) You now need to define what the build will effectively do (compile your project, generate docu- mentation, launch unit tests, etc.). To do that, you can add as many steps as needed. By default (meaning without any other plug-ins), Hudson offers 4 types of possible steps: • Execute shell: let you simply enter a shell script in the text area. You can use several environment variables (see inline help). • Execute Windows batch command: let you simply enter a Windows batch script in the text area. You can use several environment variables (see inline help). • Invoke Ant: let you invoke an Ant script. If several Ant version are available (see Sec- tion [page 156]), you can choose the one you want. You can also precise the Ant target if needed. Pressing the "Advanced" button, you will be able to specify properties and Java options. • Invoke top-level Maven targets: let you invoke Maven targets. You can specify the ex- pected targets. The "Advanced" button lets you define POM file, properties and Java op- tions. The step configuration is specific to your project. We will let you configure it as needed. 13.4.4 Post-build Actions After a build, Hudson can do some actions. Among them: • Archive the artefacts: if your build produces deliveries (such as exe, zip, or tar), or generate user documentation for instance, you can publish these artifacts on the Hud- son build page of your job. You need then to specify the path to the artifacts to publish (the reference directory is the workspace of your project). You can use the wildcard (*) to state artifacts to publish. You can also decide to keep the history of artifacts, or just the latest successfully generated ones to save space. • Publish Javadoc: if your build produces javadoc, you can publish it on the build page by giving the path to the root folder of the generated javadoc. The reference folder is the workspace. You can also use the wildcard, and can choose either archive old versions of the javadoc or not. • Publish JUnit test result report: if your build executes JUnit tests, you can publish a result report on the build page in specifying the path of the JUnit generated XML report files. If you use another test plug-in, you will find nearly the same. 159
  • Codendi User Guide • Build other projects: Your job can depend on another one. In this case, you maybe want to build another project after the current build. If so, just indicate the name of the job to build after this build. You can specify if the job has to be built even if the current build failed or not. • Email notification: Hudson is able to send emails while some events happen. You can enter a list of email addresses to be notified. A good practice could be giving a mailing list address (specific for Hudson or not) in order to notify all the team (see Section 15.1.1 [page 170] to know how to create mailing lists). Events that trigger notification are managed as followed: • Every failed build triggers a new e-mail. • A successful build after a failed (or unstable) build triggers a new e-mail, indicating that a crisis is over. • An unstable build after a successful build triggers a new e-mail, indicating that there's a regression. • Unless configured, every unstable build triggers a new e-mail, indicating that regres- sion is still there. For lazy projects where unstable builds are the norm, Uncheck "Send e-mail for every unstable build". You can also send a separate email to people who broke the build. To do this, the con- tinuous integration server must be well configured (see Section [page 157]). 13.5 Integration in Codendi As continuous integration is a good practice in software engineering, Codendi integrates Hud- son tool. We know how to install (see Section 13.2 [page 155]) and configure (see Section 13.3 [page 155]) Hudson, and how to create and configure Hudson jobs (see Section 13.4 [page 157]). Let's see now how Hudson is integrated to Codendi. 13.5.1 Hudson Service If Hudson plugin is installed and enabled on your Codendi server, each project can enable the Hudson service (see Section 6.6 [page 28] to know how to enable services for your project). Once the service is enabled, you will see a "Build" tab in the service bar of your project : the Hudson continuous integration tab. Link Hudson job with your Codendi project In order to link Hudson job with your project, select the Build tab of your project, and then select the 'Add a job' link. You need then to give the URL of the Hudson job you want to associate with your project (for instance: http://[my_ci_server]:8080/hudson/job/[my_job]). 160
  • Codendi User Guide Figure 77. Link Hudon job with your project You may also want to enable the auto trigger of the build for this job after each commit in your project repository (CVS or Subversion). If you have protected your build with a token, you can specify this token (see Section 13.4.2 [page 158] for more information). By checking this option, each commit will trigger a build of the associated job, using the pre-commit hook (you don't have anything more to do). By the way, it is possible to link several Hudson jobs with one Codendi project. Browse Hudson jobs and builds When you select the Build tab of your project, you can see a table with all the jobs associated with your project. Figure 78. Hudson jobs associated with your project For every job, you can see the current status (colored bullet left to the name of the job), the name, the last successfull build, the last failed build, if you have enabled SCM trigger or not (see Section [page 160]). Project admins will also see for each job some icons that let them modify the job or delete it (remove the link with Codendi). The name of the job is automatically detected during job creation. But you can change it if needed. This is pretty convenient if you want to make references to Hudson items (see Section [page 165]). Spaces in the name of jobs are not allowed. They are replaced by (_), in order to allow references. 161
  • Codendi User Guide The name of the job and the latest builds are hypertext links that will be opened the correspond- ing Hudson section in a frame below the table. This is really convenient to browse Hudson inter- face while staying in the Codendi interface. If you want to open the Hudson frame in a specific window, just select the 'show only this frame' link. The table provides also links to Hudson jobs RSS feed. 13.5.2 Hudson Widgets Hudson service lets you adorn your personal and project dashboard with many widgets. To know how to add widgets to your personal dashboard, see Section 3.3 [page 15]. The proce- dure is similar to add widgets to dashboard project (see Section 5.2 [page 22]). • My Hudson jobs: only available on the personal dashboard. By default, it gives an overview of all the jobs of all the projects you are member of. You can of course select the jobs you wish to display by selecting the preferences link of the widget. Figure 79. "My Hudson Jobs" Widget • Jobs Overview: this widget is only available on project dashboard. It can display an overview of all the jobs associated with this project. You can always choose the ones you want to display in the widget (preferences link). Figure 80. "Jobs Overview" Widget • Last Builds: this widget is available for both personal and project dashboard. It is linked to only one job, and show the last builds for this job (last one, last successfull, last failed). It also displays the project weather report (project trend, see Section 13.1 [page 154]). 162
  • Codendi User Guide Figure 81. "Lasts Builds" Widget • Test Results: this widget is available for both personal and project dashboard. It is linked to only one job, and show the test results of the latest build for the selected job. To display something, your job needs to execute tests and publish them. The result is shown on a pie chart. Figure 82. "Test results" Widget • Test Trend: this widget is available for both personal and project dashboard. It is linked to only one job, and show the test result trend for the job. Of course, your job needs to have tests to display something. The graph will show the number of tests (failed and successfull) along time. It can be very convenient for project managers to check that the number of tests is increasing while the number of build and commits are increasing too. 163
  • Codendi User Guide Figure 83. "Tests Trend" Widget • Build History: this widget is available for both personal and project dashboard. It is linked to only one job, and show the build history, under the form of RSS feed. For each build of the list, you can see the build number, the status and the date the build has been scheduled. 164
  • Codendi User Guide Figure 84. "Builds History" Widget • Last Artifacts of the Build: this widget is available for both personal and project dash- board. It is linked to only one job, and show the last artifacts published. To display something, your job needs to publish artifacts. Figure 85. "Last artifacts of the Build" Widget 13.5.3 Hudson References It is possible to make references to Hudson items in Codendi. There are some predefined refer- ences (job, build), but you can also create your own references if needed (see Section 6.8.1 [page 30] for more details about references) Make a reference to a Job The keyword to make a reference to a Job is: job. To make a reference to a job, you can use the expressions: • job #JobNameToReference (the job must be in the current project) 165
  • Codendi User Guide • job #project:JobNameToReference (will make a reference to the job 'JobNameToRefer- ence' of the project 'project') • job #project_num:JobNameToReference (will make a reference to the job 'JobName- ToReference' of the project with number 'project_num') Make a reference to a build The keyword to make a reference to a build is: build. To make a reference to a build, you can use the expressions: • build #XXX (there must be only one job associated with the current project, and the ref- erenced build will be the build number 'XXX' of this job) • build #AJob/XXX (will make a reference to build number 'XXX' of job named 'AJob' of the current project) • build #project:AJob/XXX (will make a reference to the build number 'XXX' of the job 'AJob' of project 'project') • build #projet_num:AJob/XXX (will make a reference to the build number 'XXX' of the job 'AJob' of the project number 'project_num') 166
  • Codendi User Guide CHAPTER 14 Wiki Service Codendi offers a Wiki service to each project. The wiki available in Codendi is based on a popu- lar wiki tool called phpWiki. 14.1 Wiki Overview 14.1.1 Wiki Definition A Wiki is a website that allows anyone to easily add content or to edit the content that is already in place. A wiki enables documents to be written collectively in a simple markup language using a web browser. A single page in a wiki is referred to as a "wiki page," while the entire body of pages, which are usually highly interconnected via hyperlinks, is called "the wiki.". Codendi offers an in- termediate representation called a "Wiki Document": it is a wiki page that is directly accessible from the project wiki main page. A defining characteristic of wiki technology is the ease with which pages can be created and up- dated. There is no review or approval process before modifications are accepted, and Codendi wikis are open to all Codendi registered users. 14.1.2 Wiki Page Formatting In Codendi wikis, there are three representations for each page: the HTML code, the web page resulting from rendering that code by a web browser, and the user-editable source code, from which the server produces the HTML. The latter format, known as "wikitext", is written in a sim- plified markup language. The reasoning behind this design is that HTML, with its large library of nested tags, is too com- plicated to allow fast-paced editing, and distracts from the actual content of the pages. It is also viewed as beneficial that users cannot use all the functionality that HTML allows, such as JavaScript and Cascading Style Sheets, because of the consistency in look and feel that is thereby enforced, and for security reasons. 14.1.3 Linking and Creating Pages Wikis are a true hypertext medium, with non-linear navigational structures. Each page typically contains a large number of links to other pages. Links are automatically created using a specific syntax, the so-called "link pattern." 167
  • Codendi User Guide Codendi wikis use CamelCase as a link pattern, produced by capitalizing words in a phrase and removing the spaces between them (the word "CamelCase" is itself an example of CamelCase). The term CamelCase comes from the uppercase "bumps" in the middle of the compound word, suggesting the bumps of a camel. Codendi wikis also allow other ways of creating wiki links by putting anything into square brack- ets. This allows the creation of page titles containing blank characters. New pages in a wiki are created simply by creating the appropriate links on a topically related page. If the link does not exist, it is emphasized as a "new" link. Following that link opens an edit window, which then allows the user to enter the text for the new page. This mechanism ensures that so-called "orphan" pages (which have no links pointing to them) are rarely created. 14.1.4 Searching Codendi wikis offer a title search, as well as a full text search. 14.2 Codendi Wikis Codendi wikis are project-specific. So two different projects may use the same page names without conflict. 14.2.1 Wiki Creation The wiki has to be initialized by a project administrator before use: simply click on the "Wiki" link in the service bar, select the wiki language, press 'Create', and wait for the creation process to complete. Please note that the language of the wiki is initialized once and for all: it cannot be changed later, and it is viewed in the selected language, whatever the user preferences. The wiki creation phase creates a default set of useful wiki pages: a welcome page, a sandbox to play with, the PhpWiki documentation, etc. 14.2.2 Wiki Permissions By default, Codendi wikis are viewable and editable by any Codendi registered user. While this is usually the best policy, some wikis should not be public. For those cases, Codendi offers a permission mechanism based on user groups, as for file releases and documents (see Section 6.10 [page 35], Section [page 100] and ???). Permissions may be set at the wiki level, and apply to all pages, or at the page level, so that only selected pages are protected. 14.2.3 Examples of Wiki Usage Project Wikis hosted on Codendi may typically be used for many different purposes. The follow- ing examples are just suggestions: • Meeting minutes: wikis are very convenient places to hold meeting minutes. Simply type the meeting name as a wiki link, click on this new link and type the minutes. Addi- 168
  • Codendi User Guide tionally, anybody can edit and correct the content later. • Project Calendar: Codendi wiki pages may include a shared calendar, that every team member can access and edit (see the CalendarPlugin page). • Documentation: a wiki is a convenient way of providing project documentation (user guide, administration guide, FAQ, etc.). This documentation can be updated at any time by any team member, partners or even customers if they have been granted proper ac- cess permissions. 14.2.4 More Documentation All Codendi wikis are initialized with some default pages, including the PhpWiki documentation. See the PhpWikiDocumentation page for a description of all the PhpWiki features: syntax, plug- ins, etc. 169
  • Codendi User Guide CHAPTER 15 Communication Services One of the Codendi objectives is to provide developers with efficient software development and project management tools. In addition, the Codendi site should quickly become the favorite communication channel of all users as it is pivotal for the project teams and their community of users to communicate efficiently. To this end, Codendi offers a series of communication services that can be customized by the project team. These include mailing lists, the News service, the Web Forums and a Instant Mes- saging Plug-in. 15.1 Mailing Lists 15.1.1 Creation Each project can create as many mailing lists (ML) as needed. To create a mailing list click on the "Lists" item in the Project Main menu, then click on the "Admin" link in the mailing list menu bar. Adding a ML is just a matter of giving it a name, a one-line description, and to specify whether it is a public or a private list. A private list won't show up on the welcome screen of the Mailing List service and is therefore only known to the project team. This will prevent other people from sub- scribing or posting messages to it. In order to minimize naming conflicts between the many MLs created by the various Codendi projects, the mailing list follows the following naming pattern: projectname-listname@lists.www.codendi.org Where: • projectname is your project short name as defined during project registration. • listname is the name you have chosen for your mailing list. Creating a mailing list implies that you are the mailing list administrator, at least at the begin- ning. As the ML administrator, you'll receive some additional instructions via e-mail shortly after the creation of the ML. This is an important mail message that contains the URLs for the ML ad- ministration and information pages and the default ML administration password generated by Codendi. Keep it in a safe place! 170
  • Codendi User Guide Tip: Create at least one Mailing List A Codendi hosted project should at least create one mailing list (or a web forum) where all users can post questions and comments. This list is typically called projectname-inter- est@lists.www.codendi.org. We strongly encourage you to follow this well established prac- tice. 15.1.2 Administration The ML administration is also entirely Web based. You can access the ML administration page by using the URL that you received when you first created the ML. In case you have misplaced the original message you can access the ML administration page at the following URL: http://lists.www.codendi.org/mailman/admin/listname The Administration page allows you to tune many ML parameters, manage list members, and administrators, privacy, new member welcome messages, etc. GNU/Mailman, the ML manager used by Codendi, is an extremely capable software and we invite you to visit the administration page at least once to get an idea about the feature set. Note that project administrators are not automatically made administrators of project mailing lists, and the administrative password for the mailing list is distinct from any of the other Co- dendi user passwords. 15.1.3 (Un)Subscription, Archive and Preferences Unless its owner marks a ML as private, any Codendi user can subscribe to a project Mailing List (ML). To subscribe to a mailing list click on the "Lists" item in the Project Main menu. From there click on the "Subscribe/Unsubscribe/Preferences" link of the appropriate ML. Then follow the instructions presented. The Codendi ML system (GNU/Mailman) also archives all the messages posted on a mailing list. Following the "Archive" link on the same page as before will bring you to archived mes- sages grouped by month. Note that the current archiving software is not MIME-aware and does not support the archiving of attachments. 15.2 News Service The News service complements your mailing lists. This service allows you to publish pieces of news related to your project. Any event in the life of your project is a good candidate for a news release: new people in the team, new software release, information on related technologies and why not your wedding announcement or the birth of your sixth child ? . Do not keep your project concealed behind a veil. Make your project life public for the benefit of all employees and for your faithful community of users. News publishing is very easy. Simply click on the "News" item in the Project Main menu and then on the "Submit" link in the News Service menu at the top of the page. From there type the title of the news and its text body. You can type URLs in the body. Codendi will detect them and transform them into a hyperlink in the published version. You can also choose whether you want the news to be public this means visible on your Project Summary page for all Codendi users or 171
  • Codendi User Guide private which means visible for your project members only. Any Codendi visitor can attach a follow-up comment to the news visible for her on your project page making each piece of news a potential forum of discussion8. In addition the Codendi Team sees all the public news published by all Codendi projects and can decide that a project news is worth publishing on the Codendi front page. A big splash indeed!! When submitting a news, you can request a promotion for the Codendi front page to the administrator. 15.3 Web Forums This is the third form of communication offered by Codendi. Web Forums are more or less equivalent to mailing list except that the message-posting takes place via a Web interface rather than email. Therefore you need to have a connection to the site to participate in the discussion because you can't prepare your message off-line, as you can with an ML. To access the Web Forums of a Codendi project, click on the "Forums" item in the Project Main menu. When a Codendi project is created, it is given three Web forums: Open Discussions, Help and Developers. These Forums and all others are open to all Codendi users both for read- ing and posting unless you decide to make them private (see below). A user can also decide to monitor a Web Forum. Monitoring a Forum will cause Codendi to automatically forward all the posted messages via e- mail thus avoiding repeated visits to the Forum Web page. Project administrators can create other Forums on demand by using the Forum Administration module that can be accessed via the "Admin" link in the News Service menu. Administrators can follow the links on this page to Add Forum, Delete Message, and Update Forum Info/Status. The Update Forum Info/Status page lets administrators make forums public or private, edit the name and description of the forum, or even delete the forum. 15.4 Instant Messaging Plug-in Codendi is bundled with a Jabber server and an Instant Messaging (IM) Plug-In that allows a certain level of integration between them. If this plug-in is active, an IM account will be automatically available to each Codendi user and they will be able to log into the Jabber server using their Codendi credentials. Furthermore, users participating in a project will be grouped together in the Jabber server, whose will auto- matically add this group to each of the participants' roster. For each project the plug-in will create a multi-user chat room (MUC) where the members of a project can chat together. Only members of a project can join its respective MUC, but once a member has joined the room he or she can invite external users. The Codendi IM plug-in comes with a Jabber client integrated into the web interface of your project. This client lets you chat into the project MUC Room (see Section [page 174]). Of course, each user can choose the client that best fits his or her needs. Several open source (and/or free) clients are available for the most common platforms, and you can find a list (non-exhaustive) of them at http://www.jabber.org/clients. Note that some clients, like Coccinella for instance, allow you to do shared whiteboard. 8Behind the scene, each piece of news is actually managed exactly like a Codendi Web Forum. 172
  • Codendi User Guide The status of a user using a Jabber client (online, busy, away) is displayed in Codendi. 15.4.1 Jabber Related Information on the Codendi Web Page Codendi provides several bits of information regarding the Instant Messaging on its web inter- face. Thus, each user has access to his roster (contact list) and the status of each of his con- tacts directly on his personal page. In order to do this, simply visit the page "My Personal Page". If the widget displaying the contact list is not visible it must be added. To do so, click on the link "Add widgets" and add the widget corresponding to "My IM Roster". Next to each user name Codendi displays a colored icon (gray, green, yellow or red) that indi- cates the status of the user: gray for "offline", green for "online", yellow for "away", and red for "busy". Users can change their status through their Jabber client. Any new approved project implies the creation of a corresponding shared group and chat room. Any new member added to the project is also added to the corresponding shared group and chat room. This new member will be automatically invited to join the project's chat room as soon as he or she connects to the Jabber server. If a member is removed from a project then he or she will also be removed from its correspond- ing shared group and chat room. If a project is suspended or awaiting validation, its corresponding chat room will be made un- available (locked) and the shared group will not be visible on the roster of project members. If a project is deleted, the corresponding chat room and shared group will be destroyed as well. 15.4.2 Jabber Client Configuration Configuring a Jabber client to use your Codendi account is straightforward. In case you are us- ing a multi protocol client the first thing you need to do is setting the communication protocol to Jabber (or XMPP). Three other pieces of information are essential for connecting to your Jabber account: your username, your password, and the address of the Jabber server you will connect to. Some Jabber clients refer to the JID (or Jabber ID) which is simply your username and the Jabber server address connected by a @ sign (eg. username@jabberhost.com), others ask ex- plicitly for your username and the Jabber server address. You can find your JID at your personal area on the Codendi web page by logging into Codendi and clicking on the link “Account Main- tenance” on the tab “My Personal Page”, or simply by accessing your “Developer Profile”. There you can find your “Instant Messaging Login”, which is formed by your Codendi username and the Codendi Jabber server address. Use the same password you use to sign in to your Codendi account. In addition to these parameters the client may ask you a name for the resource you are using to connect to your Jabber account. This is handy when you are connected to the same Jabber ac- count through different devices and so, for example, a message can be delivered to you@yourhost.com/pda instead of you@yourhost.com/office (in this case “pda” and “office” are the resources). You can fill it with any alpha-numeric string. Finally, the client needs to know the port number the Jabber server is listening to. The default value for this parameter is 5222, and most of the Jabber clients use it by default. 173
  • Codendi User Guide Some other “advanced” parameters can be configured, but it is out of the scope of this guide to talk about them, so please refer to your Jabber client documentation for further information on this topic. 15.4.3 Multi-User Chat Room (MUC) As stated before, the IM plug-in creates a multi-user chat room for each project. This room is named after the project name and is opened only for project members. You can access the MUC Room in the web interface of your project, or with a IM client. MUC Room with the web interface To enter the chat room of your project, you just need to clic on the IM tab of your project. This will automatically connect you to IM, and you will be able to start chating with the other con- nected members. The web interface of the chat room is composed of several areas: • The main window shows you the messages of all participants. The names of the partici- pants are written beside the messages, to let you better follow the discussion. The sys- tem messages (like who arrived in the room, who left) are displayed in bold. Messages are displayed without specific format, but you can add some if you want (see Tips: formatting and special commands [page 175] for that). URLs are displayed as hyper- links (and are opened in another window). Project references are also displayed as hy- perlinks (for instance, if you write the message bug #23 in the chat room, a click on the word 'bug #23' will open a new window and will lead you to the bug details page). The system does not check that bug 23 really exist in your project. it is possible to make ref- erences to other projects, but only with the pattern keyword #projectID:itemNumber. The pattern with project name is not recognized by IM. For more details about cross- references, see Section 6.8.1 [page 30]. • Just below the main window, is the writing message area. To send a message to all chat room members, select this area with the mouse, write your message, and then ei- ther click on the 'Send' button, either press the 'Enter' key. Your message will show up in the flow, preceed by your name. • The area on the right is the list of the room members, which means the users connected to the chat room. This list is updated in real time. There is a concept of private messages. If you want to talk to someone, but don't want the other to see it, you can click on the name of the person, and then write your mes- sage (the name of the user is now just below your message, which indicate he will be the only one to receive it). To come back to the usual way of doing (chat with eveybody) you just need to click again on the name of the person in the writing area, which will make the buddy name disappear. • Above the main area, the name of the chat room is written (it is the name of the project, you can not change it). Just below, you can find the topic of the room. You can update this topic by writing the special command as a message: /topic The new topic of the room • Below the writing area is located a status zone, corresponding to your IM status. This 174
  • Codendi User Guide status can be useful to tell the other if your are free to chat, or busy, etc. You can also add a free text, to express your mood of the day, or anything else! On the right, there is a small icon which lets you switch off/ swith on the sound. You need a Flash plugin in your browser to have sound. Figure 86. Multi-User Chat Room in the web interface of Codendi Tips: formatting and special commands When you type some text in the chat window, the client interprets some commands to format the text. These commands can be interpreted depending on the IM client, but most of them are working the same way. • Write in bold: you must surround your text with a star. Example: I will call you *tomorrow at 2 o'clock* • Underlign: you must surround the text with underscore. Example: I will call you _tomorrow at 2 o'clock_ • Write a hyperlink: the system will detect hyperlinks if they are starting with http:// Example : You can read http://www.codendi.com and see what I mean • Make a cross-reference to a item of your project: You can make a reference to any item of your project (artifact, bug, document, wiki page, etc.) For that, just write the reference to the item respecting the pattern keyword #itemnumber Example : You can read the document doc #185 for more details. 175
  • Codendi User Guide • Change the chat room topic: you must write the specific command /topic followed by the new name of the topic. Example: /topic Monthly Meeting • Change your nickname: You can change your nickname during the session. The other users will then see you as this new name. This feature can seem funny, but remember that the the discussion will be hard to fol- low if everybody change his nickname often. We recommand you to use this feature if it makes sens only (to differenciate two people with a close name for instance). Please note that nickname changes won't appear in chat room logs. Messages will always be alloted to their real user. To change the nickname, the command is /nick followed by your new nickname. Example: /nick Tom - at home • Smileys: You can use smileys. The web client doesn't have an interface to insert smileys, but you can add them in a textual way. They will appear like an image for the clients (even for the web one). Each client im- plements its own smileys, so use the more commons ones, and you shouldn't have any problem. Example: the text :-) will display a beautiful smile! Join a MUC Room with a client You need to inform your Jabber client the address of the conference server it must query for chat rooms. This address is simply conference.server_address, i.e. the word “conference”, a dot, and the Jabber server address. Then you will be able to retrieve the list of available chat rooms on the server. Just find the chat room corresponding to your project and join it. Of course the steps described above are very generic, and each Jabber client has its own spe- cific process. Please check your Jabber client documentation for further information about its support on multi-user chat (group chat, conferences, or simply chat rooms). Once inside the room you can invite non-members to join it. Once the user accepts the invitation he or she becomes member of the chat room. For further information on how to invite external users to chat rooms using your Jabber client please refer to its documentation. 15.4.4 MUC Room Logs Conversations in chat rooms are logged (private conversation are not). To access the log, select the link 'Logs' in the IM tab of your project. Every member of the project has access to the project room logs. By default, conversation logs of the 7 last days are displayed. You can of course change the search period, thanks to the calendar. If you don't want to specify dates, leave the field blank. Blank for start date means "from the beginning", blank for end date means "until now". Conversation logs are grouped by day. You will find the time of the message (hour and minute), the author of the message (username on the Codendi server), and of course the message itself. Nickname changes are not logged. System messages are present. This is very useful to know who was in the room when what thing has been told. URLs and cross-references will appear as hyperlinks, but special commands (see Tips: formatting and special commands [page 175]) won't be interpreted. A light horizontal line will separate conversations. Two conversations are considered as different if there has been no activity during at least 10 minutes. You can export the room logs, in CSV format. To do this, click on the Export button at the end of 176
  • Codendi User Guide the logs. The export will use your user preferences for CSV separator and date format (see Sec- tion 3.5 [page 16]). 177
  • Codendi User Guide CHAPTER 16 Survey Manager The Survey Manager allows a project team to create surveys. Providing a survey service in an environment where most services are related to software development activities may seem a bit strange at first glance. However if you remember that Codendi is about source code sharing and community building, you'll soon realize that part of the game in building a strong community is to listen to the community feedback and make it happy. Listening to your community can be done in various ways on Codendi: • through your project mailing lists and web forums, • from the feedback received when you post a piece of news on your Project Summary page • or by analyzing the profile of the submitted Support Requests over a period of time. All these communication channels allow Codendi users to push spontaneous feedback on a topic that they wholeheartedly cherish. But what if you want to collect the opinion of your com- munity on a precise number of subjects and you want the answers to be taken from a set of possible choices defined by the project team? This is precisely what the Survey Manager is for. It allows you to: • formulate a precise a list of questions • define the set of possible answers for easy statistical analysis • make the survey accessible to virtually anybody via the Intranet • review the results to identify the dominant trends in your community of users. Figure 87. Survey Manager Welcome screen 178
  • Codendi User Guide 16.1 Publishing a Survey Audience: project members You have been working hard to produce this perfectly polished survey and now you want to reach the broadest possible audience. With Codendi you can make your survey visible in a number of ways: 1. Through the Survey Manager itself: as soon as a survey is created it is visible in your Survey Manager Welcome screen (see Figure 87 [page 178]). So any Codendi user visiting your Project Summary page will see that surveys are available in the "Pub- lic Area" (survey count not null) and by clicking on "Surveys" she will be able to take whatever survey is available. 2. Project News Service: when you have your new survey ready, make sure you publish a piece of news about this survey: why you did it, who is expected to take it and type the Web location corresponding to the survey (see below). By publishing a piece of news you also have a chance to see it on the Codendi front page if the Codendi Team decides so. 3. E-mail: the survey you have created can be accessed directly via a Web pointer (URL) on the Codendi site. As a consequence you can push your survey to virtually anybody in the Corporation simply by referencing the survey Web pointer in an e-mail message, a web page or any kind of office document. Even non Codendi Users will be able to take the survey. All surveys created on Codendi can be accessed through the following Web pointer (URL): http://www.codendi.org/survey/survey.php?group_id=N&survey_id=X where N is your project ID number and X is the survey ID number as shown in the survey list displayed on the Survey Manager welcome screen. Your project ID number N is visible on the Survey Manager Administration screen (see Figure 87 [page 178]) Taking a survey is just a matter of accessing the survey by one of the previously mentioned method, answer the questions and click on the "Submit" button at the bottom of the page. A sample survey is shown on Figure 88 [page 180]. Important note: Survey Privacy The information collected in these surveys are strictly internal to Xerox. This information is being gathered to build a profile of the projects and developers being surveyed. The identity of those who answer surveys are suppressed and not viewable by project administrators or the public or third par- ties. The information gathered is used only in aggregate form, not to single out specific users or de- velopers. 179
  • Codendi User Guide Figure 88. A sample survey taken from the Codendi project 16.2 Administering Surveys Audience: project members Administrative functions of the Survey Manager can only be used by the project members. The Administration module allows you to: • Create or modify a survey • Create or modify questions • Review the survey results To access administrative functions of the Survey , go to your Project Summary page and click on the "Survey" item in the Project Main menu at the top of the screen, then select the "Admin" item in the Survey Manager menu (see Figure 87 [page 178]). From there you have access to all the Survey Administrative functions (see Figure 89 [page 181]). 180
  • Codendi User Guide Figure 89. Survey Manager Administration screen 16.2.1 Survey Structure In order to understand the survey creation and update process you must first understand that the Survey module manages two distinct pools of entities: a pool of surveys and a pool of ques- tions. As a consequence of this organization, creating a survey is a 2-step process: 1. First you create a set of questions along with the related set of possible answers. All questions for all surveys are stored in a common pool. 2. Then you create a survey mostly by giving it a title and attaching a series of previously defined questions to it. One of the interest of managing questions and surveys separately is that you can create distinct surveys and re-use the same questions in several of them if need be. 16.2.2 Creating or Editing Questions First thing first: if you want to collect people's opinion you must first define a set of questions and the possible answers for each of them. Designing a good survey is not an easy task and it requires a fair amount of work: the value derived from the survey results depends directly on the quality of your questions. A couple of advices: do not put too many questions in a survey, ques- tions must be short, clear, unambiguous and non overlapping. So take some time to think about it with your project team. To create questions click on the "Add Questions" item either in the Survey Manager Administra- tion menu or in the content of the page itself. Defining a question is simply a matter of typing the question itself and then choosing a response type. There are 5 types of possible responses (see Figure 88 [page 180] for some sample questions): • Radio Buttons 1-5: this response type will force the user to give an answer to the ques- tion on a scale from 1 to 5 using 5 radio buttons. 181
  • Codendi User Guide • Radio Buttons Yes/No: this is a variant of the previous one for questions calling for a Yes or No answer. • Custom Radio Buttons: this response type allows the project administrator to define a set of answers from which the user may choose one. The possible answers are dis- played as radio buttons. • Select Box: this response type allows the project administrator to define a set of an- swers from which the user may choose one. The possible answers are displayed in a select box. • Text Field: questions for which you want a short free text answer (one line) • Text Area: same as above but the user can enter multiple lines of text. This is when you want to have a detailed answer to the question • Comment: this is not really a question. It's a convenient way to insert comments in your list of questions. • None: Assigning this type to a question will result in the de-activation of the question. This question will disappear from all the surveys using it. As usual in Codendi the ques- tion is not deleted and all the answers collected so far in the various survey where this question is used remain untouched. At any moment in the creation phase you can display the list of existing questions by clicking on the "Show Existing Questions" button at the bottom of the screen Editing questions is also possible. To do so, click on the "Edit Existing Questions" item in the Survey Manager Administration menu or in the content of the page itself (see Figure 89 [page 181]). You are then presented with the list of questions that are currently available in your question pool. Clicking on the question identifier number in the leftmost column allows you to change the question properties. Remark: changing a question after responses have already been collected is a bad idea espe- cially when changing the question type. In this case collected data will become inconsistent with the new question type. On the other hand, correcting a typo in the question or making the ques- tion clearer is perfectly OK and doesn't impact the existing set of answers. 16.2.3 Creating or Editing a Survey Once you have created questions in the common question pool, you can create a survey and at- tach questions to it. To create a survey click on the "Add Surveys" item either in the Survey Manager Administration menu or in the content of the page itself (see Figure 89 [page 181]). Then enter the following in- formation: • The name of the survey (give it a short title) • The list of questions attached to the survey. This is a comma separated list of question identifiers (IDs) that you want to use for this survey. To see question IDs in a separate window, click on the "Show Existing Questions" and choose the appropriate question IDs from the list. The questions will appear in the survey in the same order as in the list. • The status of the survey: you can make it active or not. As long as a survey is inactive it doesn't show up in the welcome screen of the Survey Manager meaning that it is not visible to Codendi users. Similarly accessing the survey directly via its Web location will not work either. • If you allow anonymous answer or not. Allowing anonymous answers give the opportu- nity to unregistered people (or not-logged ones) to answer the survey. If you don't allow anonymous answers, only registered (and logged in) users will be able to answer the 182
  • Codendi User Guide survey. At the bottom of the screen is a list of all the surveys defined for your project. You can edit any of the survey by clicking on the survey ID in the leftmost column. Editing a survey can be also be done by clicking on the "Edit Existing Surveys" item in the Survey Manager Administration menu and then choosing the survey to edit at the bottom of the screen. While editing a survey you can change the list of questions or the order of the questions without impacting the current result set. If you remove a question from the survey, you won't be able to view the existing set of responses. However it does not mean they are lost. Re-inserting the question ID in the survey list allows you to view the set of responses again (see next section). 16.2.4 Reviewing Survey Results Audience: project members At any point in the life of the survey, project members can have a look at the existing set of an- swers that have already been given by the users who took the survey. To review the results of a given survey click on the "Show Results" item in the Survey Manager Administration menu and then click on the Survey ID number you are interested in. Figure 90. Survey Results 183
  • Codendi User Guide A list of all the questions attached to this survey will show up on the screen. Next to each ques- tion is an aggregate view of the existing answers. For questions of type "text field" or "text area" you can review the full list of answers. For radio buttons, the Survey Manager compute the total number of answers, the average value as well as the value distribution for radio button answers. Export Your Survey Results for Finer Grain Analysis If you want to further massage the results of your surveys remember that Codendi allows project ad- ministrators to export project data including survey results. For more details see Section 6.11 [page 38] 184
  • Codendi User Guide CHAPTER 17 Project Web Site 17.1 Visiting a Web Site When a new project is created on Codendi a project specific Web Site is created as well. You can access a project Web site in 2 different ways: • By forming the following URL in your favorite Web browser (where projectname is your project short name): http://projectname.www.codendi.org Or, if your server is setup in secure mode: https://projectname.www.codendi.org • Click on the "Home Page" link in the Project Main menu at the top of the Project Sum- mary page. If the project team has not yet created its own Web pages, you'll see the default project home page informing you that the site will come soon as well as a link back to the Codendi site. 17.2 Web Site Creation 17.2.1 Directory Structure and Location Each project has its own specific location where to store their collection of HTML pages along with the images or related data files and document that comes with it. The location of the direc- tory where to store all these documents is: /home/groups/projectname If you use your Shell Account (see Section 18.1 [page 189]) to log into the Codendi server and place yourself in this directory with the Unix command "cd /home/groups/projectname" you'll see 3 subdirectories: • htdocs: this is where you must place all your HTML pages including those with embed- ded PHP or SSI instructions (see below for more details). All the images, icons or docu- ments used or referenced in your Web pages must also be stored in this directory (or in 185
  • Codendi User Guide any sub-directory under htdocs). In the Apache jargon the directory / home/groups/projectname/htdocs is the Document Root of your Web Site. Tip : Apache Apache is the HTTP server developed by the Apache Consortium. It is available under an Open Source license and is by far the most popular Web server in the world with more than 60% of the market share. For more information on Apache see http://httpd.apache.org Apache expects your home page to have one of the following name: • index.html, index.htm for pure HTML pages • index.shtml for pages using Apache SSI extensions • index.php if you use embedded PHP scripts If your own home page is called index.php then rename the default index.php file cre- ated by Codendi into something else by using the following commands from your Shell Account: cd /home/groups/projectname/htdocs mv index.php index_default.php • cgi-bin: this directory is where you must place all your CGI scripts. CGI scripts can be written in a number of languages like Perl, Python, Shell or even C. • log: this is a reserved directory. Do not put any of your files in it. 17.2.2 Web Site Scripting with PHP Project members can build sophisticated project Web sites by using the PHP language. PHP, is becoming extremely popular as a server-side scripting language for the Web. PHP is easy to learn, optimized for the Web and interact nicely with SQL databases. If you decide to embed PHP scripts in your Project Web pages, first make sure to use the ".php" extensions for all the files with PHP code in it. For pure HTML pages use the "htm" or "html" ex- tensions as usual. For security reasons, your php scripts will only be allowed to access files located in the docu- ment root of your project (e.g. /home/groups/projectname/htdocs). 17.2.3 Web Site Publishing You can use various methods to publish your Web pages on your Codendi Web site: • Remote editing with HTML capable editors like Netscape or Mozilla Composer, Mi- crosoft FrontPage or Emacs with transparent ftp access • Local editing on your machine and transfer of the files either via ftp or, even better, via scp • Small changes to web pages can be made from the shell account on Codendi, using emacs or vi, but substantial editing is discouraged. Macromedia Dreamweaver 186
  • Codendi User Guide You can use DreamWeaver to design and create your project web site. As opposed to Front- Page, DreamWeaver fully support remote publication via FTP. To create a new site go to the Site -> New Site menu. In the local information, choose your site name and local root folder. For the remote information, choose FTP access and specify projectname.www.codendi.org as host and /home/groups/projectname/htdocs as the host directory. The login is your Co- dendi login. Local Editing and Remote Transfer For those of you who use an HTML editing tool that has no built-in export facility you can trans- fer your HTML files by other means. • FTP: this is the simplest method for transferring your Web pages to the Codendi remote location. Use ftp to connect to projectname.www.codendi.org and use your Co- dendi username and password to login. Once logged in issue the following command: cd /home/groups/projectname/htdocs and finally use the put (or mput) command to transfer the modified files. Check with your Web browser that everything is ok. Mind your Web Browser page cache and force page reloading to be sure you see the latest version of your pages! • SCP: scp -r * login@shell.www.codendi.org:/home/groups/projectname/htdocs/ where login is your Codendi login. The -r option stands for recursive copy and will copy all the files in the directory as well as all others in subdirectory while preserving your di- rectory structure. 17.3 Referencing the Codendi Site The Codendi Team is asking that all project Web sites hosted on Codendi display the Codendi logo on their front page. And ideally it would be great if you also cross-reference our site on other pages that are located on other servers. The rationale behind this request is twofold: • First, by referencing the Codendi site on your Web page you will allow your visitors to learn about the existence of the Codendi site, give them a chance to visit it and also let them learn about other projects hosted on Codendi. By doing so you will augment the opportunity for re-use. • The second reason is that using the Codendi logo in your Web site will automatically in- crease the Web access counter that Codendi is maintaining for you. The number of ac- cesses to your site can be viewed by visiting your Project Summary page and click on the "Statistics" link below the project description (see Figure 7 [page 23]). This will also help us to identify projects that may require additional hosting resources due to large amounts of activity. To display the Codendi logo on your project Web page use the following Web pointer: http://www.codendi.org/sflogo.php?group_id=N&type=1 Use "https" instead of "http" in the above URL if your server is setup in secure mode. 187
  • Codendi User Guide You can use this logo in anchor and image tags. For example you can associate a hyperlink to the logo that goes directly to your Project Summary page: <A href="http://www.codendi.org/projects/projectname"> <IMG src="http://www.codendi.org/sflogo.php?group_id=N&type=1 width="80" height="20" border="0" alt="Source Code Available !"> </A> Caution! Substitute the number after "group_id" (N in the example) with your own project id number. You can see what your group_id number is by visiting any of project services Web page and looking at the group_id value shown in the URL of the page (see the Location bar in your Web browser). 188
  • Codendi User Guide CHAPTER 18 Other Services 18.1 Shell Account Important Note: this feature can be deactivated by your Codendi site administrator and may therefore be unavailable in your organization. If the Codendi administrators have enabled this feature, each registered user receives its own Unix shell account on the Codendi Shell Account server. You can access your Codendi Shell Account in 2 ways: • SSH: the secured remote shell is the preferred way to connect to the Codendi Shell Ac- count server. SSH clients are available for all platforms (Windows, Linux, Unix and Mac) and allows a secure link with your personal directories. It also provides you with a num- ber of other useful utilities like scp for remote file transfer. To access your account type the following command and use your Codendi login and password to authenticate your- self: ssh -l loginname shell.www.codendi.org • Telnet: telnet comes standard with Windows and Unix environment. Use the following command to connect to the Codendi Shell Account server and provide your login and password as requested. (Remark: on some site telnet might be disabled for security rea- sons) telnet shell.www.codendi.org Whether you use SSH or Telnet, a welcome banner will be displayed right after you log in. This message tells you what are the directories you are allowed to access. Use the Unix "cd" com- mand to change the current working directory. Once logged in and if you are a member of sev- eral projects you must specify for which project you are going to work in this shell session. To this end use the following command: newgrp projectname You can use this command as many time as you want during a shell session when you are about to do work for another one of your project. 18.2 FTP Anonymous Storage Space 189
  • Codendi User Guide Each project receives its own FTP storage, the Anonymous FTP Space. If you need a controlled access to your files, it is recommended to use the web-based File Release System (Chapter 8 [page 96]). The anonymous FTP space can be used by the project members to upload any kind of docu- ments or project data and deliverables they want. This storage will then be visible to any Co- dendi users and all files placed in this directory can be freely downloaded. So make sure that you use this storage space for world readable files only. • Anonymous Users access: use an ftp client to connect to down- load.www.codendi.org. Use "ftp" as login and your email address as the password. Then cd /pub/projectname to access the FTP Anonymous space. • Project Members access: use an ftp client to connect to down- load.www.codendi.org. Use Codendi login and password and then type cd / var/lib/codendi/ftp/pub/projectname to access the FTP Anonymous space. From there project members have both read and write access which means that they can upload files. To point to this storage space in your Web pages or your email to other users simply use the following URL: ftp://projectname.www.codendi.org:/pub/projectname 18.3 SOAP API Codendi provides a SOAP API to access Codendi through web-services. At this time, only ses- sion (login/logout) and tracker services are available. A human-friendly description of the services is available at http://www.codendi.org/soap/. It is a list of services, with a description of each function, its input, output and documentation A more detailed description of the services is also available with the more formal WSDL lan- guage at http://www.codendi.org/soap/?wsdl. The WSDL also includes the types definition. 18.4 Codendi Command Line Interface (CLI) Another way to use Codendi is to use the command line interface (CLI). It's a client application that use the SOAP API to interact with the Codendi server. At this time, only session (login/logout) and tracker services are available. The CLI is currently missing a few features of the SOAP API (e.g. it is not possible to attach a file, a CC address or a dependency to an arti- fact), and the mail notification is not active with the CLI. The full CLI documentation is available at http://www.codendi.org/documentation/cli/pdf/en_US/Codendi_CLI.pdf 18.5 Codendi Eclipse plugin Codendi provides a plugin for the Eclipse IDE. This plugin will let you browse your artifacts, modify them and create new ones within Eclipse environment. 190
  • Codendi User Guide Figure 91. Codendi plugin for Eclipse IDE The Codendi Eclipse plugin is to be deployed on Eclipse 3.2 and needs JRE 1.5 The Eclipse plugin can be installed and updated with the updatesite mechanism. The Codendi update site for this plugin is: http://www.codendi.org/plugins/eclipse/updatesite/ To install the Codendi plugin with Eclipse update site mechanism, please follow the instructions below: 1. In the Eclipse main toolbar, select Help > Software Update > Find and install... 2. Check Search for new features to install, then click Next 3. Press the New Remote Site... button 4. Fill the dialog box with a. Name: Codendi (for instance) b. URL: http://www.codendi.org/plugins/eclipse/updatesite/ 5. Check the Codendi box (you can expand to see the feature details), and then press OK 6. Eclipse will ask you to accept or not the license. If you want to accept the license, check "I accept the terms in the license agreement" 7. Then click the Finish button. 8. Eclipse will ask you to check the feature to install. Press the Install button 9. Eclipse will download the feature and may need to restart to complete the installation 10. Enjoy Codendi! 191
  • Codendi User Guide The full Eclipse plugin documentation is available at http://www.codendi.org/documentation/eclipse/pdf/en_US/Codendi_Eclipse_Plugin_User_Guide .pdf 192