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
- Any special requirements
Guidelines
- Guidelines for OHWR administrators to create a project.
- Project structure guidelines
- Release guidelines
OHWR features
GitLab provides the following modules per Project
- Issue management & time tracking (via tickets)
- Documents module
- Files module
- Wikis (1 per project)
- Forums (can create multiple forums per project)
- git 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 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. - 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.
- Show in the title on which version a problem appeared, like "V1 - power connector wrong".
- Set the Milestone 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 Milestone tab will be helpful to track when Issues have been
solved and gives a very nice overview.
For this to work the Issues need to have a "Milestone" set. - The Discourse forum is the preferred way of communication.
- Use Git for all kinds of files requiring version management: HDL and software/firmware, schematics, PCB layout, manufacturing files, etc.
- 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
- 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.
Anyone wanting to commit changes to a project will have to be
authenticated as a developer or manager on that project.
Forums
Each project has it's own forum. E.g., this OHR Support project has the forum https://forums.ohwr.org/c/ohr-support.
Other
- Open Source Guides ** Open Source Guides were created and are curated by GitHub
25 January 2022