Project Structure Guidelines
Top project & sub-projects
This structure is suitable for complete hardware module design projects, with PCB, HDL, software and tests.
* Name * | * Repository * | * Wiki * | * Issues * | * Documents * | * Files * | * Mailing-list * | * News * | * Roadmap * | * License * | |
Top/main project | NO | YES | YES[1] | YES | YES | YES | YES | Optional | N/A | |
Hardware sub-project (PCB, mechanical parts) -hw | Hardware design of | YES | YES | YES | Optional | Optional | Optional | Optional | Optional | CERN OHL |
Gateware sub-project (HDL) -gw | Gateware for | YES | YES | YES | Optional | Optional | Optional | Optional | Optional | LGPL |
Software sub-project (driver, library, test program) -sw | Software support for | YES | YES | YES | Optional | Optional | Optional | Optional | Optional | GPL |
Test sub-project (production/functional tests[2]) -tst | Testing support for | YES | YES | YES | Optional | Optional | Optional | Optional | Optional | GPL |
Tips to re-structure a project following those guidelines.
Remarks
- Keep issues separate (e.g. PCB revision, HDL versions), top project gathers issues from all sub-projects.
- No need for several git repositories per project.
- To minimise the drawback of having several wikis to edit, the sub-project wiki is optional for small projects.
- In big projects, the hardware sub-project can be split in two: PCB and mechanical.
- If needed an additional sub-project for firmware can be considered (e.g. code for embedded CPU).
- The roadmap and issue features can be used to create release changelog.
Pending questions:
- Usage of files vs documents?
- The default project page should be the wiki. "Overview" should be renamed in "About" (or something similar).
- There is a link from parent project to sub-project but not the other way round!
TODO
- Make a template project.
- It would be nice to have the top project display the news from all subprojects
Single project
A single project structure is preferable in case of non-mixed project (e.g. HDL library, stand-alone PCB, test framework).
- Project -> repository, issue, wiki, files
Git repositories
Git sub-modules will be used in order to organise and solve
dependencies.
This way we will:
- avoid dependency on hdlmake in HDL projects.
- have more flexibility.
- avoid copy of source files.
- avoid huge & messy repositories (c.f. PTS).
Proposed git sub-modules structure:
- Hardware (PCB, mechanical parts, no sub-modules)
- Software (e.g. dedicated board driver, library and test program)
- Software dependencies (e.g. carrier, fmc-bus, zio)
- HDL sources (operational, testing)
- HDL dependencies (e.g. hdl cores)
- Test (specific production/functional tests)
- Testing framework (e.g. PTS), common libraries
Git repository usage policy
- No binary or huge simulation files.
-> Binary files (.bin, .pdf, ...) only in the "Files" section. - ONE person (maintainer) commits to master.
- No rebase of master.
- Other developers commit to proposed_master.
- See Repository-use
Testing (production and functional)
- Common part in it's own project -> PTS (single project scheme).
- Specific test in a sub-project of the board.
- Test system
-> Automate installation as much as possible -> install scripts.
-> Documentation. - Store testing log files in MTF (CERN specific).
-> Note: A log file must correspond to a serial number (barcode).
TODO
- Wiki page "How to batch upload files in MTF" (CERN specific).
- Write a unique, platform independent
API for testing the
hardware modules.
-> single r/w, block r/w, wait irq, sdb, fmc eeprom, flasher
-> C lib + python wrapper
-> part of the fmc-bus?
-> raw backend with direct memory mapped access => for non-fmc boards - Get rid of rawrabbit/gnurabbit.
-> Requires a replacement first (cf. block read/write support in spec-sw). - Clean-up jpts.
About releases (To be discussed)
- min/maj (v3.2) or date-based (v02.2014) -> sdb is not foreseen for date-based versioning.
- wiki release pages
- templates
- md5sum of binaries
- changelog only in one place
- automate page creation (Would be nice to have), python-redmine to be investigated...
- git tags
- package releases (pcb+hdl+sw ?+test?)
- zip/tar of sources+binaries?
- update doc
non-ohwr projects (CERN specific)
- Use official cern git repos.
- Page on wikis.cern.ch as the central info point.
- One JIRA space per board to gather issues.
-> Issues summary in the wiki. - Official/operational gateware release location is on nfs:
-> /acc/loacl/share/firmware/ - Binary files location: nfs (operational), wiki (public)
TODO
- Write a "how to migrate a svn repo to git" wiki page.
- Update wiki page template.
-> Issues summary
Matthieu Cattin, 25 June 2014
-
Automatically gathers issues from sub-projects.
-
Board specific part of PTS.