Project Structure Guidelines
(red) Don't take this page as a guideline yet, it's just some random thoughts for the moment.
How to organise projects?
- Several git repos per project OR several sub-projects? -> Probably
several sub-projects...
- Keep issues separate (e.g. pcb revision, hdl versions), top project gathers sub-project issues.
- Is it possible to have several repo per project in OHR? -> not yet as I understood -> not needed with the sub-project scheme.
- Several sub-projects = several wikis to edit -> how to minimise drawback? -> optional sub-project wiki for small projects.
- Different types/size of project (pcb+hdl+sw+pts, hdl only, pcb only, ...) -> optional sub-project wiki, files for small projects.
- 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!
Proposed ohwr project structure:
-
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)
- 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?
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).
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, Feb. 2014