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 as meeting minutes, informal, high-level descriptions, objectives can also be put in a wiki page, for example called Documents. Make sure that via the wiki pages you are directed to these Documents too, as most users will only see the wiki pages.
Adding new users
New users should apply for an account with one of the ohwr administrators. There is no way to register yourself. Note that anyone, even without an account, can read all information. Registering does not give you access to more data.
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
- Maintainer (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.
- Guest - can read. Not used on ohwr.org as all projects are accessible for everyone without needing a login.
Repositories
- Policies about Repository Use gives ideas how large repositories with many contributors can be handled.
Git
A project will include a git repository. Anyone wanting to commit changes to a project will have to be authenticated as a developer or manager on that project. Notably for older projects the page Gitlab migration of ohwr faq may give you useful information.
Forums
Each project has it's own forum. For example, 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