Louis Suárez-Potts
louis@openoffice.org
a. Project leads. OpenOffice.org has now two categories of project leads: Sun and non-Sun employees. This guide addresses the concerns of both categories of project leads; no distinction is made. In truth, this guide provides but a start; more will be added as the week progresses and new questions surface. As stated above, please read over this guide, and use the Help documentation in sc-OpenOffice.org. Questions should be sent to me, and not to the discuss list. Why? Because we haven't notified the community yet. That will happen next week.
b. Community: Goolie and Louis will work on a message for the community, to be sent out 29 June. For the casual user OpenOffice.org on SourceCast will make little difference. However, SourceCast does use a registration model, and even the most casual user is automatically, if invisibly, logged in. What is more, depending on the permissions granted a user, she will see different aspects of the site. This will be explained to the community at large, and the advantages of registering will be explained. All this will be detailed in the message to be sent out 29 June. We expect that the message will be the start of a continuing explicatory phase.
i. There might be some resistance within the OpenOffice.org community, for the user will, for the first time, be given the option to register, which implies both good and bad things. The messaging will have to deal with that. I do not, actually, anticipate too many objections, for explicit registration will bring with it considerable advantages (project leads willing). These will include the ability to join projects and act in a manner that is more engaged with the work at hand. But it may also create a tiered structure, whereby visitors who are not members see one version of the site, and registered members who are part of projects see other parts. The simpler structure of t-OpenOffice.org gives the appearance of a horizontality that actually still exists within sc-OpenOffice.org, although it is more nuanced. But the appearance of that horizontality shifts.
ii. To overcome some of the objections, the community will have to be apprised of the extensive and clear site documentation (the Help and Site FAQs) that explain sc-OpenOffice.org's functionality. Concepts such as IssueZilla, CVS, SSH, and so on, are clearly explicated, with examples, in the Hosted Tools section of the Help. (Note: the SSH documentation will be up-to-date by the time the site goes live.)
iii. Mailing List. As well, the community will be informed of the differences. Subscribing/unsubscribing will be the same, indeed, easier. A significant plus, however, will be the much-longed-for introduction of searchable archives. (Note: It is anticipated that by the time the changeover is complete, in the middle of July, OpenOffice.org will be using a newsgroup server [NNTP]. For the sake of simplicity and clarity, this guide won't touch on that.)
a. Files Migrated. All the OpenOffice.org-specific files that make up Tigris OpenOffice.org have been successfully moved to SourceCast OpenOffice.org. The files that will be migrated at the last minute, in the week of July 13, include those few files that have not already been migrated, as well as files updated since the initial migration. Until then, we should continue to proceed normally on t-OpenOffice.org; and we should also be testing sc-OpenOffice.org.
b. Files Added. Besides the test and bogus files, the most obvious instance of added files are those that come packaged with SourceCast, such as the SourceCast Help files and Site FAQs.
i. Help Files, including Site FAQ. The files included here provide a fairly thorough primer of SourceCast and how to use it. Actually, as will become apparent, this guide will use many of the files to explain how to set permissions, how to load files, how to edit projects.
a. Structure. Both sc-OpenOffice.org and t-OpenOffice.org manipulate CVS files. Hence, there can only be so much difference between the two platforms. The biggest change is that sc-OpenOffice.org doesn't automatically support the idea of a sub-project in the same way that t-OpenOffice.org does. Rather, sc-OpenOffice.org supports the more sophisticated concept of a "resource." But, in both cases, what is being controlled is access to a CVS module. A resource can be thought of as a file or group of files over to which a certain role pertains; and precise permissions can be associated with this role. A project owner can request that a new resource be added to his project and that a new role be associated with this resource. Once that role is available to the project owner (something the domain admin must do), the project owner can then add any number of project members to that project with that role, and he or they will only have access to that resource. Why? Their project role has limited their access to other resources. And, yes, a member can have more than one role.
i. Example. Mary wants to create a new sub-project, "talk" within the "VoiceRecognition" project. Solution: the project owner submits a request to the domain admin (who can add new resources to projects) that a new resource corresponding to "voicerecognition/talk/" be added. The domain admin must also create a new role "talkdeveloper," say, which directly corresponds to the new resource just created. Fred, the owner of "VoiceRecognition" can then add Mary to the project with the new role, "talkdeveloper." If she only has that new role (the "talkdeveloper" role), she will only have access to that "sub-project," or more accurately, resource.
ii. I have no doubt that there will be questions related to this modification. Those with domain admin privileges can work through the process by logging in, and from their Start Page, click on "Adminster Roles" in the top, uner "Admin Options." From there, go to the "Roles & Resources" link on the SourceCast navbar. And add a new resource. Experiment with the provisions of the process.
iii. The advantage of this method is that it allows for greater precision and ultimately security. The drawback is that it adds a step in which the project owner must petition (send a request to) the domain admin to implement the desired change. However, as OpenOffice.org is growing, and including more and more non-Sun project owners, this added step is all the clearer an advantage.
b. Categories. In the current sc-OpenOffice.org, projects are listed by generic "category." This will change, as we do not really need to use category at all. Rather, we can create one category: OpenOffice.org, and transplant (with some changes to prevent an immune reaction) the current HTML page describing the projects, leaders, and purposes.
c. Little has changed in content. This implementation of SourceCast is similar to the current OpenOffice.org implementation on Tigris. But there are changes, both for project owners, admins, and for registered, regular users, though the changes a typical user will encounter are fairly minor. Among the things that have changed, the most obvious is:
i. The Login. This login in feature will automatically login any nonregistered user as "anonymous." Registered users must log in manually each new session. The advantages of the login feature are many, including the ability of registered users to go automatically to their "start" page upon logging in. This page lists those projects they have joined or created, as well as other available projects, by category. Projects in which the user does not have a direct role are not presented by default. For instance, sc-OpenOffice.org creates the new concept of groups for projects and members (see: //project/www/docs/DomAdminUserGroups.html).
ii. And, from an administrative perspective, the login feature allows some control of information and visitor traffic, if wanted.
iii. Logging in. Project leads—admins—must login using their current t-OpenOffice.org account username and password to appreciate (to use) SourceCast's sophisticated admin features. Take, for example, the Help. When we were constructing the help system, the idea was to accord Help files with the user. A project leader will see a different Help set of files than a nonregistered user. Thus, to get the most out of the Help (including the links I am citing here), project leaders must log on. And I encourage you to use the Help files.
iv. Use the Help. This is especially true right now, while this site is under construction. For instance, all of t-OpenOffice.org's many projects are not visible unless one enters as a domain admin. This will change, to be sure.
d. Much has changed (or can change) in spirit. The great advantage of sc-OpenOffice.org is that it encourages a more engaged role on the part both of the visitor (who can now more easily browse through a project and its files) and of the current project owners.
i. Users, for instance, can now more easily (with the merest click of a button) upload documents to the project site, project lead permitting. And users can now "join" a project, a concept more or less impossible to realize with t-OpenOffice.org, where one might join a most a mailing list. This means that the micro-community making up a project will interact more with the website element, as opposed to primarily living in the mailing list space.
e. Permissions and project roles. Perhaps the most important change has to do with the advent of a sophisticated permissions system which allows the project leader the ability to more easily grant specific roles to developers who have joined his project. With t-OpenOffice.org, there were rather few permissions at play: one could read or write or read and write any particular module; these corresponded to the CVS modules making up the project and determined the role of the individual. SourceCast folds in a level of useful complexity that project leaders can take advantage of. For instance, as I discussed above, in "Structure," a project owner can modify the permissions of a developer to grant him or her access to particular files; or can create new roles with a mix of permissions per file. I anticipate that this, one of the more involved areas of the process, will generate some confusion. So:
i. For information on roles and permissions, please see the general category of help for project owner administration: //project/www/docs/ProjectOwnerAdmin.html, and the more specific help on permissions: //project/www/docs/DomAdminRoles.html. A good description of project roles: //project/www/docs/ProjectRoles.html
ii. However, the best way to understand the kinds of roles and permissions over which a project leader has access is to create a practice project and adjust the roles and privileges of willing subjects. For the most part, this is routine; but you can grant the user a role that elevates her beyond the casual visitor. You can even create new roles (if not permissions) that will allow your project to grow smoothly. As well, members of the project may request new roles of the project lead or leads.
iii. In fact, you can delegate much of the responsibility of running the project to a willing user. Yes, t-OpenOffice.org effectually offers the same advantage; these are, after all, predicated on CVS modules. But sc-OpenOffice.org allows greater flexibility in managing users and work on a project and in providing valuable incentive to developers interested in joining a project. For information on how to manage project members, please see: http://look.openoffice.org/project/www/docs/ProjectOwnerMembers.html
iv. Or, you can simply leave the permissions in a state that resembles the current condition. That is, users will only be qualified as registered users (if that) and will have few privileges. They will still be able to view projects, and their associated files, but they will not have the full privileges of a registered user, let alone a more trusted user. But: there is no special need to alter the naïve state of a developer.
v. Getting used to the increased sophistication of sc-OpenOffice.org permissions will doubtless take some getting used to, as it may not be apparent to project leads why they should change the status quo. But: if granting more rights to registered users results in growing the project and developing the code faster….
a. Registered users. Any registered user can propose a new project. Will it be accepted? That depends on the domain admin, who must decide on the project. And who is the domain admin? It can be a person, or a group, such as is the present case, with t-OpenOffice.org.
b. Project leads. Currently, project leads can create new projects only after the proposal has been approved by other project leads. The same can obtain with sc-OpenOffice.org.
c. How is it done? Very easily. Or at least the proposal simple enough to make. For information on the procedure, please see: // . I recommend that everyone go through the process of creating a project. In creating a project, one can, initially (it can be changed later), specify the index page content (or deploy one of your own), assign roles, invite members, and set up mailing lists and news pages. For these reasons it is very important that project leads be familiar with the process.
a. Documents. Currently, on t-OpenOffice.org, files (documents, etc.) are committed to a project's modules by, usually, the project leader. This power structure can continue into sc-OpenOffice.org., and the project lead can continue to be the sole committer of documents. Should the project lead wish to change the power structure, however, and allow others who have decided to join the project to contribute documents, text, or news items, this can easily be done by changing the permissions of the registered users to allow it. See http://look.openoffice.org/project/www/docs/ProjectOwnerDocuments.html for a more detailed explanation.
b. News. Each project now (or can have) have a space in which relevant news and announcements are featured. This is an advantage that probably does not need to be highlighted, but say there is important news relevant to the XML project. Or that the XML project lead would like to keep tabs on what others in XML development are doing. The project news page could be dedicated to features related to XML. For more information on this, please see http://look.openoffice.org/project/www/docs/ProjectNews.htm
c. Issues. Sc-OpenOffice.org makes managing issues related to a project a quite a lot easier. Not only can the project lead now manage issues pertaining to his or her project, but he can now more easily track those issues and assign them. For more information on this, please see: http://look.openoffice.org/project/www/docs/ProjectOwnerIssues.html
d. Mailing Lists. There are some changes. "All project mailing lists are created with anzu, an open-source mail alias and list management extension of qmail simple mail transfer protocol (smtp). Anzu supports multiple domains, enabling each project to define and manage its own unique set of mailing lists for the project domain." This much is familiar. As is: "If you created your project as a standard development project, your project begins its life with five built-in, pre-configured mailing lists." What differs is that it is much easier for project owners/leaders to edit mailing lists: to add/delete them, as well as modify and moderate them. For more information on this topic, please see: http://look.openoffice.org/project/www/docs/ProjectOwnerMailingLists.html
e. Source code. Sc-OpenOffice.org has an option whereby each project can control its own source code. To date, OpenOffice.org is not so modular as that is necessary.
a. t-OpenOffice.org's documentation page attempted to consolidate information on the tools developers use, among other things. It still will, but the Hosted Tools link in the Help files provide a more fluid account of the hosted tools, such as CVS, IssueZilla, etc. Please see http://look.openoffice.org/project/www/docs/hostedtools.html . (For what it is worth, OpenOffice.org is still unique in using SSH2, so that element in the help files will be changed.
a. The work that has to bed done until the new OpenOffice.org goes live will focus on accommodating the legacy OpenOffice.org to the new structure. For project leads, the primary focus should be on becoming familiar with managing projects and project members. The help files are of inestimable value in this; as are the site FAQs, which I have not touched on at all.