My Reproducible Repository Guidelines 😃

Making PheKnowVec a Reproducible Research Repository

"Computational science has led to exciting new developments, but the nature of the work has exposed limitations in our ability to evaluate published findings. Reproducibility has the potential to serve as a minimum standard for judging scientific claims when full independent replication of a study is not possible ...The field of science will not change overnight, but simply bringing the notion of reproducibility to the forefront and making it routine will make a difference." -Roger Peng

PheKnowVec Reproducibility Guidelines

Now that you have an idea of what GitHub tools are available, I'd like to provide some additional guidelines for how I would like to make the PheKnowVec project reproducbible. Since there are no agreed upon standards for developing reproducible research repositories, consider what follows as a working draft of my best attempt at defining a new GitHub-based standard:

Create Issues for Everything:
I have created several issue templates to make it easier to document a wide range of tasks.

• Issues should represent a single idea, task, bug, question, or suggestion
• All correspondence about an issue, whenever possible, should be conducted within that issue
• When an issue has been addressed, close it, but don't be afraid to re-open it if more work is needed
• Specific labels have been created to help track issues, use them!

Track Progress:
I have created specific Project Boards in an effort to keep things organized. These boards have been automated, meaning issues will be automatically added to specific boards if a project is assigned at the time of creation.

• Please remember to assign labels when making new issues. If you are unsure of which project to assign an issue to, let me know by mentioning me in the issue by including @callahantiff in the issue description.
• If you have addressed a new issue, go to the project it's connected to and drag the issue to the "In Progress" board.
• If you create an issue that is related to an existing Milestone, make sure you assign it at the time of creation.

Communicate Openly:
The Wiki has been designed in an effort to keep collaborators up to date on the project.

• Provided detailed documentation of current analyses and work being performed. See the description of our initial manuscript analysis, here, as an example.
• Update meeting minutes religiously and referencing or link, when needed, to current issues.
• Add evidence of success to the homepage. Providing links to the products of this work is an important aspect of reproducible science.
• Provide links to collaborators via hyperlinking their GitHub username when referenced in meetings or other documentation -- share the love!

If the Code Changes a Bit, You Must Commit!:

• Frequently committing code in the development branch is a must.
• Only tested code should be merged with the master branch, otherwise commits should be made to the development branch.
• Document code releases with Zenodo; a DOI can be obtained after the initial release.

---

If you have any suggestions for additional guidelines, please let me know here.