Communication Tools =================== One of the Tuleap objectives is to provide developers with efficient software development and project management tools. In addition, the Tuleap site should quickly become the favorite communication channel of all users as it is pivotal for the project teams and their community of users to communicate efficiently. To this end, Tuleap offers a series of communication services that can be customized by the project team. These include mailing lists, the News service, the Web Forums and a Instant Messaging Plug-in. .. _mailing-lists: Mailing Lists ------------- .. _creation: Creation ```````` Each project can create as many mailing lists (ML) as needed. To create a mailing list click on the "Lists" item in the Project Main menu, then click on the "Admin" link in the mailing list menu bar. Adding a ML is just a matter of giving it a name, a one-line description, and to specify whether it is a public or a private list. A private list won't show up on the welcome screen of the Mailing List service and is therefore only known to the project team. This will prevent other people from subscribing or posting messages to it. In order to minimize naming conflicts between the many MLs created by the various Tuleap projects, the mailing list follows the following naming pattern: :: projectname-listname@SYS_LISTS_HOST Where: - ``projectname`` is your project short name as defined during project registration. - ``listname`` is the name you have chosen for your mailing list. **Note** Creating a mailing list implies that you are the mailing list administrator, at least at the beginning. As the ML administrator, you'll receive some additional instructions via e-mail shortly after the creation of the ML. This is an important mail message that contains the URLs for the ML administration and information pages and the default ML administration password generated by Tuleap. Keep it in a safe place! **Tip** A Tuleap hosted project should at least create one mailing list (or a web forum) where all users can post questions and comments. This list is typically called ``projectname-interest@SYS_LISTS_HOST``. We strongly encourage you to follow this well established practice. Administration `````````````` The ML administration is also entirely Web based. You can access the ML administration page by using the URL that you received when you first created the ML. In case you have misplaced the original message you can access the ML administration page at the following URL: :: http://SYS_LISTS_HOST/mailman/admin/listname The Administration page allows you to tune many ML parameters, manage list members, and administrators, privacy, new member welcome messages, etc. GNU/Mailman, the ML manager used by Tuleap, is an extremely capable software and we invite you to visit the administration page at least once to get an idea about the feature set. **Note** Note that project administrators are not automatically made administrators of project mailing lists, and the administrative password for the mailing list is distinct from any of the other Tuleap user passwords. (Un)Subscription, Archive and Preferences ````````````````````````````````````````` Unless its owner marks a ML as private, any Tuleap user can subscribe to a project Mailing List (ML). To subscribe to a mailing list click on the "Lists" item in the Project Main menu. From there click on the "Subscribe/Unsubscribe/Preferences" link of the appropriate ML. Then follow the instructions presented. The Tuleap ML system (GNU/Mailman) also archives all the messages posted on a mailing list. Following the "Archive" link on the same page as before will bring you to archived messages grouped by month. Note that the current archiving software is not MIME-aware and does not support the archiving of attachments. Global Preferences `````````````````` Setting a membersip maximum ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Tuleap has patched Mailman so that the system forge adminstrators can set the maximum number of users per mailing list. This feature is disabled by default. To enable it you need console access to the Tuleap machine. :: $ vi /usr/lib/mailman/Mailman/mm_cfg.py Say you want to limit the number of members to 100. Add/ edit the following lines :: # Limit number of users in mailing lists. # Possible values: integer or 'false' LIST_MEMBER_MAX = 100 Then restart the service :: $ service mailman restart This will limit the number of people who can be subscribed to the mailing lists using the mass-import functionality of Mailman. However, it will not prevent members from subscribing one-by-one via the interface or directly through the mailing list. .. _news-service: News Service ------------ The News service complements your mailing lists. This service allows you to publish pieces of news related to your project. Any event in the life of your project is a good candidate for a news release: new people in the team, new software release, information on related technologies and why not your wedding announcement or the birth of your sixth child ? . Do not keep your project concealed behind a veil. Make your project life public for the benefit of all employees and for your faithful community of users. News publishing is very easy. Simply click on the "News" item in the Project Main menu and then on the "Submit" link in the News Service menu at the top of the page. From there type the title of the news and its text body. You can type URLs in the body. Tuleap will detect them and transform them into a hyperlink in the published version. You can also choose whether you want the news to be public this means visible on your Project Dashboard for all Tuleap users or private which means visible for your project members only. Any Tuleap visitor can attach a follow-up comment to the news visible for her on your project page making each piece of news a potential forum of discussion [#f1]_. In addition the Tuleap Team sees all the public news published by all Tuleap projects and can decide that a project news is worth publishing on the Tuleap front page. A big splash indeed!! When submitting a news, you can request a promotion for the Tuleap front page to the administrator. Web Forums ---------- This is the third form of communication offered by Tuleap. Web Forums are more or less equivalent to mailing list except that the message-posting takes place via a Web interface rather than email. Therefore you need to have a connection to the site to participate in the discussion because you can't prepare your message off-line, as you can with an ML. To access the Web Forums of a Tuleap project, click on the "Forums" item in the Project Main menu. When a Tuleap project is created, it is given three Web forums: Open Discussions, Help and Developers. These Forums and all others are open to all Tuleap users both for reading and posting unless you decide to make them private (see below). A user can also decide to monitor a Web Forum. Monitoring a Forum will cause Tuleap to automatically forward all the posted messages via e- mail thus avoiding repeated visits to the Forum Web page. Project administrators can create other Forums on demand by using the Forum Administration module that can be accessed via the "Admin" link in the News Service menu. Administrators can follow the links on this page to Add Forum, Delete Message, and Update Forum Info/Status. The Update Forum Info/Status page lets administrators make forums public or private, edit the name and description of the forum, or even delete the forum. .. _instant-messaging-plug-in: Instant Messaging Plug-in ------------------------- .. attention:: Deprecation notice Instant messaging plugin is no longer maintained. Tuleap is bundled with a Jabber server and an Instant Messaging (IM) Plug-In that allows a certain level of integration between them. If this plug-in is active, an IM account will be automatically available to each Tuleap user and they will be able to log into the Jabber server using their Tuleap credentials. Furthermore, users participating in a project will be grouped together in the Jabber server, whose will automatically add this group to each of the participants' roster. For each project the plug-in will create a multi-user chat room (MUC) where the members of a project can chat together. Only members of a project can join its respective MUC, but once a member has joined the room he or she can invite external users. The Tuleap IM plug-in comes with a Jabber client integrated into the web interface of your project. This client lets you chat into the project MUC Room (see `Multi-User Chat Room (MUC)`_). Of course, each user can choose the client that best fits his or her needs. Several open source (and/or free) clients are available for the most common platforms, and you can find a list (non-exhaustive) of them at http://www.jabber.org/clients. Note that some clients, like Coccinella for instance, allow you to do shared whiteboard. The status of a user using a Jabber client (online, busy, away) is displayed in Tuleap. Jabber Related Information on the Tuleap Web Page ````````````````````````````````````````````````` Tuleap provides several bits of information regarding the Instant Messaging on its web interface. Thus, each user has access to his roster (contact list) and the status of each of his contacts directly on his personal page. In order to do this, simply visit the page "My Personal Page". If the widget displaying the contact list is not visible it must be added. To do so, click on the link "Add widgets" and add the widget corresponding to "My IM Roster". Next to each user name Tuleap displays a colored icon (gray, green, yellow or red) that indicates the status of the user: gray for "offline", green for "online", yellow for "away", and red for "busy". Users can change their status through their Jabber client. Any new approved project implies the creation of a corresponding shared group and chat room. Any new member added to the project is also added to the corresponding shared group and chat room. This new member will be automatically invited to join the project's chat room as soon as he or she connects to the Jabber server. If a member is removed from a project then he or she will also be removed from its corresponding shared group and chat room. If a project is suspended or awaiting validation, its corresponding chat room will be made unavailable (locked) and the shared group will not be visible on the roster of project members. If a project is deleted, the corresponding chat room and shared group will be destroyed as well. Jabber Client Configuration ``````````````````````````` Configuring a Jabber client to use your Tuleap account is straightforward. In case you are using a multi protocol client the first thing you need to do is setting the communication protocol to Jabber (or XMPP). Three other pieces of information are essential for connecting to your Jabber account: your username, your password, and the address of the Jabber server you will connect to. Some Jabber clients refer to the JID (or Jabber ID) which is simply your username and the Jabber server address connected by a @ sign (eg. username@jabberhost.com), others ask explicitly for your username and the Jabber server address. You can find your JID at your personal area on the Tuleap web page by logging into Tuleap and clicking on the link “Account Maintenance” on the tab “My Personal Page”, or simply by accessing your “Developer Profile”. There you can find your “Instant Messaging Login”, which is formed by your Tuleap username and the Tuleap Jabber server address. Use the same password you use to sign in to your Tuleap account. In addition to these parameters the client may ask you a name for the resource you are using to connect to your Jabber account. This is handy when you are connected to the same Jabber account through different devices and so, for example, a message can be delivered to you@yourhost.com/pda instead of you@yourhost.com/office (in this case “pda” and “office” are the resources). You can fill it with any alpha-numeric string. Finally, the client needs to know the port number the Jabber server is listening to. The default value for this parameter is 5222, and most of the Jabber clients use it by default. Some other “advanced” parameters can be configured, but it is out of the scope of this guide to talk about them, so please refer to your Jabber client documentation for further information on this topic. Multi-User Chat Room (MUC) `````````````````````````` As stated before, the IM plug-in creates a multi-user chat room for each project. This room is named after the project name and is opened only for project members. You can access the MUC Room in the web interface of your project, or with a IM client. MUC Room with the web interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enter the chat room of your project, you just need to clic on the IM tab of your project. This will automatically connect you to IM, and you will be able to start chating with the other connected members. The web interface of the chat room is composed of several areas: - The main window shows you the messages of all participants. The names of the participants are written beside the messages, to let you better follow the discussion. The system messages (like who arrived in the room, who left) are displayed in bold. Messages are displayed without specific format, but you can add some if you want (see :ref:`Formatting and special commands ` for that). URLs are displayed as hyperlinks (and are opened in another window). Project references are also displayed as hyperlinks (for instance, if you write the message bug #23 in the chat room, a click on the word 'bug #23' will open a new window and will lead you to the bug details page). The system does not check that bug 23 really exist in your project. it is possible to make references to other projects, but only with the pattern keyword #projectID:itemNumber. The pattern with project name is not recognized by IM. For more details about cross-references, see :ref:`reference-overview`. - Just below the main window, is the writing message area. To send a message to all chat room members, select this area with the mouse, write your message, and then either click on the 'Send' button, either press the 'Enter' key. Your message will show up in the flow, preceed by your name. - The area on the right is the list of the room members, which means the users connected to the chat room. This list is updated in real time. There is a concept of private messages. If you want to talk to someone, but don't want the other to see it, you can click on the name of the person, and then write your message (the name of the user is now just below your message, which indicate he will be the only one to receive it). To come back to the usual way of doing (chat with eveybody) you just need to click again on the name of the person in the writing area, which will make the buddy name disappear. - Above the main area, the name of the chat room is written (it is the name of the project, you can not change it). Just below, you can find the topic of the room. You can update this topic by writing the special command as a message: :: /topic The new topic of the room - Below the writing area is located a status zone, corresponding to your IM status. This status can be useful to tell the other if your are free to chat, or busy, etc. You can also add a free text, to express your mood of the day, or anything else! On the right, there is a small icon which lets you switch off/ swith on the sound. You need a Flash plugin in your browser to have sound. .. figure:: ../images/screenshots/sc_webmucrooms.png :align: center :alt: Multi-User Chat Room in the web interface of Tuleap :name: Multi-User Chat Room in the web interface of Tuleap Multi-User Chat Room in the web interface of Tuleap **Tip** .. _formatting-and-special-commands: **Formatting and special commands:** When you type some text in the chat window, the client interprets some commands to format the text. These commands can be interpreted depending on the IM client, but most of them are working the same way. - **Write in bold:** you must surround your text with a star. Example: I will call you \*tomorrow at 2 o'clock\* - **Underlign:** you must surround the text with underscore. Example: I will call you \_tomorrow at 2 o'clock\_ - **Write a hyperlink:** the system will detect hyperlinks if they are starting with http:// Example : You can read http://tuleap.net and see what I mean - **Make a cross-reference to a item of your project:** You can make a reference to any item of your project (artifact, bug, document, wiki page, etc.) For that, just write the reference to the item respecting the pattern keyword #itemnumber Example : You can read the document doc #185 for more details. - **Change the chat room topic:** you must write the specific command /topic followed by the new name of the topic. Example: /topic Monthly Meeting - **Change your nickname:** You can change your nickname during the session. The other users will then see you as this new name. This feature can seem funny, but remember that the the discussion will be hard to follow if everybody change his nickname often. We recommand you to use this feature if it makes sens only (to differenciate two people with a close name for instance). Please note that nickname changes won't appear in chat room logs. Messages will always be alloted to their real user. To change the nickname, the command is /nick followed by your new nickname. Example: /nick Tom - at home - **Smileys:** You can use smileys. The web client doesn't have an interface to insert smileys, but you can add them in a textual way. They will appear like an image for the clients (even for the web one). Each client implements its own smileys, so use the more commons ones, and you shouldn't have any problem. Example: the text :-) will display a beautiful smile! Join a MUC Room with a client ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You need to inform your Jabber client the address of the conference server it must query for chat rooms. This address is simply conference.server\_address, i.e. the word “conference”, a dot, and the Jabber server address. Then you will be able to retrieve the list of available chat rooms on the server. Just find the chat room corresponding to your project and join it. Of course the steps described above are very generic, and each Jabber client has its own specific process. Please check your Jabber client documentation for further information about its support on multi-user chat (group chat, conferences, or simply chat rooms). Once inside the room you can invite non-members to join it. Once the user accepts the invitation he or she becomes member of the chat room. For further information on how to invite external users to chat rooms using your Jabber client please refer to its documentation. MUC Room Logs ````````````` Conversations in chat rooms are logged (private conversation are not). To access the log, select the link 'Logs' in the IM tab of your project. Every member of the project has access to the project room logs. By default, conversation logs of the 7 last days are displayed. You can of course change the search period, thanks to the calendar. If you don't want to specify dates, leave the field blank. Blank for start date means "from the beginning", blank for end date means "until now". Conversation logs are grouped by day. You will find the time of the message (hour and minute), the author of the message (username on the Tuleap server), and of course the message itself. Nickname changes are not logged. System messages are present. This is very useful to know who was in the room when what thing has been told. URLs and cross-references will appear as hyperlinks, but special commands (see :ref:`Formatting and special commands `) won't be interpreted. A light horizontal line will separate conversations. Two conversations are considered as different if there has been no activity during at least 10 minutes. You can export the room logs, in CSV format. To do this, click on the Export button at the end of the logs. The export will use your user preferences for CSV separator and date format (see :ref:`account-maintenance`). .. [#f1] Behind the scene, each piece of news is actually managed exactly like a Tuleap Web Forum.