Project Structure Guidelines
(red) Don't take this page as a guideline yet, it's just some random thoughts for the moment.
One top projects with several 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)
- 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!
=> 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
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, ...)
git submodules
- Avoid dependency on hdlmake in hdl projects
- More flexible
- Better structured -> avoid copy of sources
- Avoid huge & messy repo (c.f. PTS)
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)
- git vs svn (git for dev, svn for releases?)
- migrating a svn repo to git
- committing change from git to svn
- Official/operational releases location
- Binary files location (wiki, edms, nfs, ... ?)
- wikis.cern.ch for doc and jira for issues?
Matthieu Cattin, April 2014