Skip to content

Drake Lab Project Policy

Jump to bottom
Eric Marty edited this page Sep 12, 2023 · 11 revisions

Page Editor: @allopole
To request edits to this page, open an issue, and tag @allopole

This page covers policy concerning naming, archiving and tracking of all projects done in Drake Lab.

Come here first when beginning a new project of any kind. Includes steps to set up project repository.

Additional information on setting up a computation project can be found on this page.

Drake Lab Project Policy

Definitions

Project: A collection of all the documents, data and code related to an intended product.

Product: The outcome of a project. Product may be a paper, dissertation chapter, website, software package, or a collection of these intended to be released together.

What is a Drake Lab Project?

Any individual or team research or work done at UGA resulting in or intended to result in a product.

This includes but is not limited to:

  • Dissertation (typically each chapter should be a separate Project.)
  • Sponsored student projects
  • Grant-funded research

Note about Intellectual Property: All intellectual work done at UGA or as part of your work as a student or employee of UGA is the intellectual property of UGA. (See UGA IP Policy.) UGA (Drake Lab) can license use of the material you create here to you if you leave UGA.

What is NOT a Drake Lab Project?

  • personal documents (letters to editor, peer reviews, opinions, etc.)
  • proposals
  • presentations (those go on presentation database - put on wiki)
  • any task or thing without a protocol. If you can't write up a plan for it, it isn't a project.

Note: GitHub has a concept called "Projects" which should not be confused with our definition of a project. GitHub's "projects" are a way to manage tasks within a repository. In our usage, the Drake Lab Project is the repository.

Elements of a Project

A Project has the following elements:

  • protocol (required): A written plan. All projects must have a protocol, not just experimental projects. Link to Drake Lab protocol templates are here. The protocol document may be a pdf file or a file called README.md, which will then be automatically displayed on the main page of the GitHub repository for the project.

  • README.md: If your protocol document is not called README.md, you should include a separate README.md which includes at minimum the full project name, originator, collaborators and the name of the protocol file. README.md is displayed on the main page of the GitHub repository for the project.

  • required metadata

  • data

  • code

  • documents: Any other written material related to the project.

  • Product or Intended Product: A collection of one or more related products such as:

    • a data archive (dryad, etc.)
    • a paper
    • a website
    • software

  • topic tags (optional): topic tags can be added on GitHub to help people search for your project. See instructions

Note: Other than the requirement that a README.md be present at the top level, there is no particular requirement as to the directory structure of the project.

Project Repositories

Where do I keep my project?

Every Drake Lab Project must be set up as a repository on GitHub under a Drake Lab organization.

Currently, these are:

If your work is under CEID:

Does it have to be a GIT Repository?

No, not exactly. You don't have to use Git on your own computer to manage your project. You can simply create a repository online at https://github.com/DrakeLab or another Drake Lab GitHub organization, then manually upload project files to it using these instructions:

https://help.github.com/articles/adding-a-file-to-a-repository/

However, if your project involves any code, you should create a git repository for your project, either in R Studio or on the command line. The GitHub copy of the repository should be the "origin", and you should push your changes from your local copy of the repository, where you do your work, to the GitHub copy.

When do I create the GitHub repository for the Project?

As soon as your project exists, meaning as soon as you have written the protocol. You should write the protocol as soon as you have a plan.

If you are not managing your project with Git, then you should at least create an empty repository on GitHub and upload your Protocol. The remaining files can be uploaded periodically or no later than at end of project before the final Product is released.

When is the project complete/over?

A project is considered over when the product has been produced.

Spinoffs

Projects which continue after a product has been produced should be spun off or forked into a new project with a new intended product and a new (related) name.

Example: drake-extinctionGeometry1 –> drake-extinctionGeometry2

For example, a second paper arising out of the same research should be part of a new project forked from the original project.

Project Naming Conventions

All new projects should be named using the following conventions. Existing Drake Lab repositories may be renamed in the future. If you are transferring your repository over to a Drake Lab GitHub organization, you should also rename it following these conventions.

This naming convention may still need some thinking/more examples: • how to label lab projects vs small group projects vs aero projects.

naming template examples
Individual Projects: surname-description drake-extinctionGeometry1
evans-zika-vectors
Team Projects: projectname-description
drakelab-description 		aero-spatialSimulation
drakelab-smallpox-eradication-visualization

Publishing

The Drake Lab project repository should be considered the private, internal full record of the history of the project. The Product is the public content and may be separate from the Project itself. The project repository itself should usually remain private. The Product may be in the form of a paper, website, and/or permanent data and code archive on Dryad or similar. This product will typically contain some but not all of the content contained int he project repository, and will not contain the full git history. The project repository should link to these final, external products.

FAQ

How do we handle grant requirement conflicts / lab conflicts / NDAs, etc.

  • If, for example, it's a CDC project that you happen to be working on here, that's not a "Drake Lab Project" and need not be on drake lab GH.
  • Proprietary data and sensitive material can be stored outside the repo and referenced in the repo.

What about non-sequential / parallel projects?

  • Address with addenda to the protocol/readme within a single "project".
  • Or, use one top-level protocol/readme that points to protocols for different components of the project.
  • Or, spin off project (it's reasonable to have multiple projects with same goal). Each project will have its own repository and related name: - drake-extinctionGeometry1 - drake-extinctionGeometry2
  • Or, establish a hierarchy of projects with hierarchical names:
    - drake-masterProject
    • drake-masterProject-subProj1
    • drake-masterProject-subProj2

What about projects currently on Google Sites?

  • For active projects that live on Google sites or some other lab server, Take the time to create an empty repository GitHub with only a README that points to the google sites folder.
  • For completed projects on Google sites, doing the above is optional for now. Eventually, we will try to establish pointer repositories for all past drake lab projects. This may take some time.

What about projects already on the DrakeLab or Project-Aero GitHub organizations?

  • If they are active projects and private repositories, they should eventually be renamed according to the naming conventions, and the full name entered in Description, and topics added. If this is disruptive to your workflow, then it should at least be renamed once the project is done and before the repository is made public.

  • If the repository is already public, leave it as is.

What if my Project is an R Package that needs to be a GitHub repository with a specific format and name?

Separate the project from the product. Name the project according to the naming conventions, and create a separate repository for the package. If all your work is done in the package repository, the project repository should at least contain a minimal README functioning as a protocol and pointing to the package repo. That way, when the package is ready to go public, the package repo can simply be made public, or forked first then made public. The full git history for the package should be preserved somewhere (in a private copy, or in the "project" repository) even if the public package repository is "cleaned up."

Who has access to the repository, who can change or delete it?

Currently, anyone in Drake Lab can create, edit or delete any repository. Currently, all Drake Lab members are "Owners" of the DrakeLab GitHub organization, with full admin privileges.

We will soon be changing most people's permissions to "Member" from "Owner." The default repository permissions for organization Members will be set to "write" instead of "admin" or "owner", which will make things more secure and allow certain repositories to be viewable by only some lab members. A few people will continue to be "Owners" or Members with "admin" privileges, and these people (John, Andrea, one or two more) could still see everything.

Any sensitive or proprietary data should be (and continue to be) isolated outside of the DrakeLab GitHub organization.

Instructions for creating a GitHub Repository

  • Log in to GitHub.
  • Click on the "New" button.
  • Select DrakeLab or project-aero as the owner.
  • Enter a repository name following our project naming conventions.
  • Enter the full project name as the Description.
  • Select Private
  • Leave Initialize this repository with a README unchecked if you will be add your protocol as REAMDE.md later.
  • Leave Add .gitignore: None and Add a license: NONE for now. You can add these later if you need them.
  • click Create Repository

Add Optional Topic Tags

After you have created your repository, you may add Topic Tags to help people search for your project by topic. To add topics, click on manage topics under the description:

...

List of suggested topics:

  • ews
  • zika
  • malaria
  • simulation
  • need a curated list of tags

Lab Links

Clone this wiki locally