Project Structure Guidelines
(red) Don't take this page as a guideline yet, it's just some random thoughts for the moment.
Top project & sub-projects
This structure is suitable for complete hardware module design projects, with PCB, HDL, software and tests.
-
Top/main project -> wiki, files, issues (gathering sub-projects
issues).
- PCB project -> repo, issue, wiki (optional), files (optional)
- Gateware project (hdl) -> repo, issue, wiki (optional), files (optional)
- Software project (driver, lib, test prog) -> repo, issue, wiki (optional), files (optional)
- Test project (prod/functional tests), board specific part of PTS -> repo, issue, wiki (optional), files (optional)
Remarks
- Keep issues separate (e.g. pcb revision, hdl versions), top project gathers issues from all sub-projects.
- No need for several git repos per project.
- To minimise the drawback of having several wikis to edit, the sub-project wiki is optional for small projects.
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
- Template project.
Single project
A single project structure is preferable in case of non-mixed project (e.g. HDL library, stand-alone PCB, test framework).
- PTS project, test framework, common libraries/classes -> repo, issue, wiki, files
- HDL cores -> repo, issue, wiki, files
git submodules
- Avoid dependency on hdlmake in hdl projects
- More flexible
- Better structured -> avoid copy of sources
- Avoid huge & messy repo (c.f. PTS)
Proposed git submodules structure:
- pcb
- sw
- sw dependencies (e.g. carrier, fmc-bus, zio)
- hdl
- hdl dependencies (e.g. hdl cores)
- test
- pts framework, common lib
- sw (e.g. carrier driver)
Releases
- min/maj (v3.2) or date-based (v02.2014)
- wiki release pages
- templates
- md5sum of binaries
- changelog only in one place
- automate page creation (Would be nice to have)
- git tags
- package releases (pcb+hdl+sw ?+test?)
- zip/tar of sources+binaries?
- update doc
Binary files (.bin, .pdf, ...)
- only in "Files" section
Testing (production and functional)
- PTS (Production) -> also include functional tests?
- Common part in it's own project
- Specific in a sub-project of the board OR in a sub-project of PTS.
- Install script (build a pts machine from scratch).
- What to do with Julian's PTS?
- The gnurabbit/rawrabbit case... (needed until we have dma
support in a generic spec driver).
-> unique API for testing, platform independent (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
-> PTS log storage location? (MTF?)
git repos
- No binaries or huge simulation files
- ONE person (maintainer) commits to master
- Other developers commit to proposed_master
- See Repository-use
non-ohwr projects (CERN specific)
- Use official cern git repos.
- How to migrate a svn repo to git -> TODO .
- 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 ()
Matthieu Cattin, April 2014