Codendi User Guide
"Collaborative Software Development and
 Project Management for the enterprise"
          www.codendi.o...
Copyright © 2000-2008 Xerox Corporation, Codendi.
This document is licensed under the GNU General Public License version 2...
Table of Contents

     1.Introduction.......................................................................................
6.10.5. Additional Information on User Groups ....................................................... 38
       6.11. PROJ...
7.13.10. Email Notification Settings ........................................................................ 93
8. File R...
10.5.2. Importing Existing Source Code ................................................................. 131
            1...
14.1.1. Wiki Definition ............................................................................................. 167
...
List of Figures
      1. The Codendi Home Page ..............................................................................
51. Browsing the CVS repository - A sample session ............................................................ 109
52. Qu...
Codendi User Guide




CHAPTER 1

       Introduction



The goal of the Xerox Code eXchange Initiative (Codendi) is to tr...
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)




                           ...
Codendi User Guide




CHAPTER 2

         Codendi Site Overview



Codendi is a Xerox Web Site available at http://www.co...
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 ...
Codendi User Guide




ing.

Using the Software Map you can browse Codendi hosted projects according to any of these cri-
...
Codendi User Guide



    •   Use the Search box in the Codendi Main menu on the left hand side or on the upper
        ri...
Codendi User Guide



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

Updating...
Codendi User Guide




User Guide. The same user guide is used throughout the Codendi site in the "Help" links that
you'll...
Codendi User Guide




2.2.4 The Search Facility
Codendi allows you to search almost any piece of Codendi information thro...
Codendi User Guide




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

Boo...
Codendi User Guide




CHAPTER 3

        Becoming a Codendi Citizen




3.1 Classes of Citizens
Before we go further into...
Codendi User Guide




As suggested above, the first thing to do for a newcomer is to create her own account on Co-
dendi....
Codendi User Guide




           And what if I loose both my login and password? Gee! In this case use the search box and...
Codendi User Guide




    •   Monitored Forums lists forums that you are currently monitoring, by project. To cancel
    ...
Codendi User Guide




    6.11 [page 38] for details). The import/export format is CSV format. Like CSV norm is not
    i...
Codendi User Guide




CHAPTER 4

        Creating a New Project



So - you are a freshly registered Codendi user and you...
Codendi User Guide




        ration (services, trackers, documents, references, ...) ? Make your old project a template
...
Codendi User Guide




4.2 Post-Registration Configuration
The first thing to do after you receive the confirmation for yo...
Codendi User Guide




CHAPTER 5

       Project Summary



The Project Summary page is the entry point of a Codendi hoste...
Codendi User Guide




5.2 Project Summary Page Content
A sample Project Summary page is available in Figure 7 [page 23]. ...
Codendi User Guide




                            Figure 7. A sample Project Summary Page



Codendi allows project admin...
Codendi User Guide




    that it shows additional information about each of the service (e.g. total number of open
    b...
Codendi User Guide




CHAPTER 6

        Project Administration



Whenever you enter the Project Summary page of a given...
Codendi User Guide




         johnd
         steve.robinson@xerox.com
         bob.johnson@xerox.com
         smith3
   ...
Codendi User Guide




                         Figure 8. A Sample Project Administration Page




6.3 Project Public Info...
Codendi User Guide




Location: Page Admin Content

Codendi proposes three types of projects:

    •   Project: This is t...
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Codendi 4.0 User Guide
Upcoming SlideShare
Loading in...5
×

Codendi 4.0 User Guide

26,005

Published on

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

Published in: Technology, Business
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
26,005
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
355
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Codendi 4.0 User Guide

  1. 1. Codendi User Guide "Collaborative Software Development and Project Management for the enterprise" www.codendi.org Version 3.6
  2. 2. 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.
  3. 3. 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
  4. 4. 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
  5. 5. 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
  6. 6. 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
  7. 7. 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
  8. 8. 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
  9. 9. 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
  10. 10. 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
  11. 11. Codendi User Guide Figure 1. The Codendi Home Page 2
  12. 12. Codendi User Guide Figure 2. The Codendi Home Page, with a different theme (with tabs) 3
  13. 13. 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
  14. 14. Codendi User Guide Figure 3. Codendi Web Page Flow Chart 5
  15. 15. 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
  16. 16. 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
  17. 17. 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
  18. 18. 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
  19. 19. 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
  20. 20. 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
  21. 21. 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
  22. 22. 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
  23. 23. 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
  24. 24. 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
  25. 25. 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
  26. 26. 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
  27. 27. 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
  28. 28. 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
  29. 29. 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
  30. 30. 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
  31. 31. 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
  32. 32. 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
  33. 33. 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
  34. 34. 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
  35. 35. 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
  36. 36. 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
  37. 37. 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

×