Administrator guide
Requesting a project
Please send an email to Javier.Serrano (insert a "@" here) cern.ch in order to ask for a project to be created. You will need to specify:
- A project name (used in the wikis, use a logical code like FMC ADC 100M 14b 4cha, you may modify afterwards)
- A project id (used in the URL, use a logical code like fmc-adc-100m14b4cha, impossible to change)
- Brief description of your project
- Type of license
- Initial team
- Repository type: svn or git (hard to change afterwards). Git is recommended.
- Any special requirements
Guidelines for OHWR administrators to create a project.
OHWR features
Redmine provides the following modules per Project
- Issue management & time tracking (via tickets)
- News module
- Documents module
- Files module
- Wikis (1 per project)
- Forums (can create multiple forums per project)
- Subversion repositories (1 per project)
- Mailing lists (1 per project)
Recommended setup & usage
We recommend the following usage of the OHR project functionality:
- Use the Wiki for storing the information you want to conserve about your project, but for which you don't have specific documents; meeting minutes, informal, high-level descriptions, objectives, etc. Also, the wiki is the entry place for most people into the project, so it's good to have a quick intro and a status table in it. Here's an example (sample source code at attachment:spec_wiki.txt). When you modify a Wiki page, fill in the Comment field at the bottom of the edit window. This way the History button becomes more useful (see FMC Delay wiki history) and will give in itself a good overview of the progression.
- Use the News section for publishing important events, such as a new release or a review meeting.
- Use the Issues tracker to create issues, tasks, milestones and
deadlines for your project, and assign it to your team members.
Think of issues as "tickets" they allow you to plan tasks and future
features, as well as to be used for bug tracking.
- For any problem found, create an Issue.
- Set the Target version for the Issue (see Roadmap).
- When it's resolved, let the engineer who solved it add comments and set the Issue status to Resolved.
- Then the project manager will verify if everything is OK (he may verify things like if the documentation is updated and other actions to be taken). Once he agrees, he may set the Issue status to Closed.
- The Roadmap tab will appear when Versions have been defined in the Setting tab. This may be helpful to track when Issues have been solved and gives a very nice overview (see SVEC Roadmap). For this the Issues need to have a "Target version" set.
- The mailing list is the preferred way of communication, but you can also use forums.
- Use subversion (SVN) or Git for all kinds of files requiring version management: HDL and software/firmware, schematics, PCB layout, manufacturing files, etc.
- Use the Documents module for providing "release" versions of
Documents; Typically you would show versions 1.0, 2.0 and 3.0 on the
Documents section, and all the intermediate steps (1.1, 2.3.1, etc)
would be managed via the SVN.
For images on the wiki site we usually create a Document called 'images'. From the wiki pages you can then point to the files that you put there. So no images attached to the wiki page as that looks a bit ugly at the bottom of a page. - Similarly, use the Files section for "release" versions of important files, such as binary installation programs, drivers, schematics, gerber files, firmware etc. Again, intermediate versions of these should be managed via subversion.
One alternative to the use of the Documents and Files modules is to have a dedicated documentation wiki page with links to important files in the SVN repository. This has the advantage of not duplicating files and the disadvantage of a (potentially) less intuitive navigation experience for the occasional visitor.
Adding new users
New users should apply for an account with the Register link (top-right of the screen). They will have to be approved by an administrator (Javier).
An administrator can register new users via the following link: https://www.ohwr.org/users/new
If you are not an administrator and need to create lots of new users, please open a ticket on ohr-support. You will need to specify the user names and email addresses there - an attached text file is recommended.
Once approved, users can be given roles on a project via the project's Settings / Members tab by a project manager.
Roles
When a project manager adds a user, he has to set the Role. These are the current Roles in ohwr:
- Administrator - can do everything
- Manager (of a project) - can do everything, but only in a certain project
- Developer (of a project) - like manager, except: manage documents, create forums, manage wiki pages and manage news.
- Reporter (of a project) - Only able to create new issues and read-only rights on the rest.
Repositories
- Policies about Repository Use gives ideas how large repositories with many contributors can be handled.
Git
If you have requested it, your project will include a git repository.
Actually Git is the most used repository type that is also more flexible
than SVN
See the dedicated wiki page for details.
SVN
If you have requested it, your project will include a subversion repository. All project's repositories are available on the following URL:
You can calculate the complete url of your repository by adding /
and
your project's identifier to that url. For example, the source code of
this page is on the ohr-support
repository:
http://svn.ohwr.org/ohr-support
This URL is publicly available on read-mode (everyone can "update" from these repositories).
Anyone wanting to commit changes to a project will have to be authenticated as a developer or manager on that project.
Create an SVN repo
cd /var/svn
sudo svnadmin create <repo-name> --fs-type fsfs
sudo chown -R www-data <repo-name>
If you only want to browse the source code, notice that Redmine provides a nicer interface via its "Repository" tab (you should see it on the toolbar, above this text). It is also possible to include links to particular releases or files (see the "wiki editing guide"/help/wiki_syntax_detailed.html for details).
Mailing Lists (Sympa)
If you have requested it, your project will include a mailing list. Mailing lists are managed via a sympa interface.
OHWR's mailing lists interface is available here:
You can calculate the complete url of your mailing list's by adding
/sympa/info/
and your project's identifier to that url. For example,
ohr-support
's mailing list page is here:
http://lists.ohwr.org/sympa/info/ohr-support
From there, you can browse the mailing list's archive, list of users, etc.
Mailing list archives are publicly available. There's no way to make private mailing lists.
If you are a project's manager, an account will be created for you on the sympa system. Your login and password will be the same as you use on the ohwr site. You will have owner rights over that list.
Appart from that, sympa's subscriptions are separated and independent from the rest of ohwr's accounts; It's possible to be a member of a project, and not be subscribed to its mailing list (in fact, newly created users are NOT automatically subscribed to the project's mailing list; they have to proactively subscribe - see below). It's also possible to be subscribed to a sympa mailing list while not having a project account (this is useful for external mail-only collaborators).
There isn't any procedure for automatically subscribing new project users to a mailing lists; only list owners are created automatically from project managers. The sympa web interface provides the lists owners with a way to mass-subscribe lots of users via uploading of a text file. We however recommend keeping the subscription voluntary.
The instructions for joining a list can be found on each project's "Mailing List" tab; see ohr-support mailing list page for an example.
Mailing lists are open; anyone can send an email to them, including unregistered users. Emails from unregistered users will be moderated by the mailing list owners (they will receive a private email when an email from an unregistered user arrives).
Backup
In order to make a full server backup, you may download the Rakefile from our repository link
Please read its comments and configure it properly before using it.
21 January 2015