Guidelines for laboratory projects

These guidelines apply to most open projects in the lab (particularly bachelor/master students and their supervisors). Unless you have a reason to do otherwise, follow the guidelines below.

Source code and documentation

  • All documentation (wiki, install instructions, …) should be written in English.
  • The source code should be in a version control system (preferably git).
  • The source code should be publicly available, preferably on GitHub under CRoCS virtual organization (contact Petr or Martin to set-up the repository).
  • There should be a licence file in the repository root folder (preferably MIT licence). Shall there be any third party code in the repository, it should be mentioned in the documentation (along with its licence!).
  • There should be a comprehensive ReadMe.md file in the repository root folder containing at least:
    • brief description of the project,
    • project authors,
    • project licence (a note on third-party code, if applicable),
    • links to other project resources (e.g. CRoCS project wiki).
  • The documentation (ideally GitHub wiki) should contain at least:
    • build/install instructions (Are there any dependencies?),
    • configuration/run instructions,
    • developer documentation (as good as you can manage :-}),
    • project authors,
    • project licence (a full list of third-party code with their licence, if applicable),
    • links to other project resources (e.g. CRoCS project wiki).
  • If the project is a part of a bachelor/master thesis at FI MU, link the official thesis repository from readme and wiki pages.

Development process

  • Phase 1:
    • Set-up the repository at the very beginning of writing the code.
    • Select proper license (MIT preferred)
    • Try to document continually, piece by piece.
  • Phase 2:
    • You can use the GitHub issue tracker to keep your work organized – put application requirements as open issues.
    • Write code nicely, write tests (you'll thank yourself later on!).
  • Phase 3:
    • Set-up an automatic build tests on TravisCI. The sooner, the better.
    • Ask someone to try to build and install your system before finalization (ideally by reading the instructions in the documentation).
  • We'll be happy to give you/your student an introduction to the necessary tools (git, GitHub, TravisCI, …). Contact Petr or Martin, if interested. (Can be demonstrated at OpenLab.)

Miscellaneous

  • If you want to be publicly identifiable in GitHub's virtual organization CRoCS, you have to change your organization membership to public (in your account settings).
  • The demonstration repository with TravisCI integration can be found in this repository.

To be done...

  • Example real project on github (powertracesimulator? - Rudo)
  • Add examples (links) for every item
  • Move (or fork) repositories from older work under crocs-muni
  • Upload older relevant source codes