Skip to content

O
OHR Support

Administrator guide

Last edited by Erik van der Bij
Page history

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:

  1. A project name (used in the wikis, use a logical code like FMC ADC 100M 14b 4cha, you may modify afterwards)
  2. A project id (used in the URL, use a logical code like fmc-adc-100m14b4cha, impossible to change)
  3. Brief description of your project
  4. Type of license
  5. Initial team
  6. Repository type: svn or git (hard to change afterwards). Git is recommended.
  7. Any special requirements

Guidelines

OHWR features

Redmine provides the following modules per Project

  1. Issue management & time tracking (via tickets)
  2. News module
  3. Documents module
  4. Files module
  5. Wikis (1 per project)
  6. Forums (can create multiple forums per project)
  7. svn or git repositories (1 per project)
  8. Mailing lists (1 per project)

Recommended setup & usage

We recommend the following usage of the OHR project functionality:

  1. Use the Wiki for storing all information you want to conserve about your project. As the wiki is the entry place for most people into the project, so it's good have some standard sections: Project description, an image, Specification, Project information, Contacts, Status. Having the same look-and-feel for all projects helps the readers too.
    Here's an example (sample source code at attachment:spec_wiki.txt).
    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.
    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.
  2. Use the News section for publishing important events, such as a new release or a review meeting.
  3. 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.
    • Show in the title on which version a problem appeared, like "V1
      • power connector wrong".
    • 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.
  4. 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.
  5. The mailing list is the preferred way of communication, but you can also use forums.
  6. Use subversion (SVN) or Git (most often used) for all kinds of files requiring version management: HDL and software/firmware, schematics, PCB layout, manufacturing files, etc.
  7. 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.
    Specific documents (in the form of pdf or .doc) such meeting minutes, informal, high-level descriptions, objectives can also be put as Documents. Make sure that via the wiki pages you are directed to these Documents too, as most users will only see the wiki pages.

[8. 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.] not existing anymore since move to OpenProject; please use a dedicated 'Document'.

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

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:

http://svn.ohwr.org

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:

http://lists.ohwr.org

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.

12 June 2018

Files