search

callahantiff / Abra-Collaboratory

git reproducible - version control your ideas
GNU General Public License v3.0
6 stars 5 forks source link

TODO - Project Organization: Reviewing the repository #4

Closed callahantiff closed 5 years ago

callahantiff commented 5 years ago

Task: Review the repo

Description:
By now you probably received an email to join the Abra-Collaboratory project as a collaborator. If you are willing, please join and explore the repository. Harrison has been very helpful with helping me to come up with an awesome name for the repo and a pretty sweet catch phrase.

Unfortunately, not all aspects of a project can easily be cloned or forked. I have found a manual way to make this possible. There are ways to improve some automatization, but this will come at the cost of being less “approachable” to novice users. So, without going too far down the rabbit hole, we have a repo that can be cloned, which is a good starting point.

Let me know what you think (I encourage you to use the issues to do this! :D). Once we have it in a place we like, we should talk about how to disseminate it a bit more for additional feedback.

@LEHunter, @tuh8888, @magic-lantern - please let me know what you think! 🙏 😄

LEHunter commented 5 years ago

This looks great! I love the detailed instructions on how to create your own (including copying project boards -- maybe submit an issue to GitHub on that one?). You might want to put a pointer to your "why do this" squib up near the top....

callahantiff commented 5 years ago

Thanks for the feedback @LEHunter!

tuh8888 commented 5 years ago

I agree, it looks great. I think using the development branch to make changes is the way to go since the projects and issues aren't synced across forks. I think the tutorial could be generalized with {project name} to emphasize that the purpose of cloning isn't to make a new Abra-Collabratory, but to use it as a template project.

callahantiff commented 5 years ago

@emastej thank you for testing the process to download and personalize the repo! I appreciate you pointing out the issues in the bug issue template and for helping me improve the documentation in the README.

magic-lantern commented 5 years ago

@callahantiff - This is a great project and I look forward to using it for my projects!

I've spent some time reviewing and have some comments/questions for you. I've already made minor updates on a few wiki pages and the readme; the below items are more substantive so I wanted to review with you (and the others collaborating here):

callahantiff commented 5 years ago

Response: Thanks @magic-lantern, your detailed feedback and comments are VERY helpful.

@callahantiff - This is a great project and I look forward to using it for my projects!

I've spent some time reviewing and have some comments/questions for you. I've already made minor updates on a few wiki pages and the readme; the below items are more substantive so I wanted to review with you (and the others collaborating here):

  • PheKnowVec is a private repository. Abra-Collaboratory is a public repository. Recommend removing references to PheKnowVec (except where showing screenshots). Perhaps just use Abra-Collaboratory as the base example? However, if PheKnowVec will become public, this change wouldn't be necessary.

I completely agree, I have removed references to this project. Ideally, I would like to point to people who have forked this repo.

  • Verify Issue Templates Transfer If person is forking Abra-Collaboratory to create their own reproducible research project, they have to enable Issue tracking. By default clones are meant to push code to parent repository, not be a stand-alone repository. See https://softwareengineering.stackexchange.com/questions/179468/forking-a-repo-on-github-but-allowing-new-issues-on-the-fork for a mini guide on how to do this.

  • [ ] @magic-lantern are you suggesting here that we add information to the readme that instructs people to do this?

  • Recommendations for Reproducible Repository Guidelines

    • Commit code often (at least daily); smaller changes are much easier for people to understand, validate, or even revert if there is a problem. Multi-day breaking changes should be done in a branch, still committed at least daily, and then merged in when ready.
    • Write comments at commit time explaining what has changed
    • README.md should be use for basic documentation (think Abstract of a paper)
    • Wiki for extended documentation
    • Create tests for software - Software engineering principles to improve quality and performance of R software. PeerJ Computer Science 5:e175 https://doi.org/10.7717/peerj-cs.175
    • Data processing pipeline should be in git. See recommendation on reproducibility spectrum image available at https://science.sciencemag.org/content/sci/334/6060/1226/F1.large.jpg?width=800&height=600&carousel=1 (from Roger Peng article you've already cited) In working with HIPAA data, you can't save data to a public git repo, but you can and should save everything you do with your data.

These are great! I have incorporated them into the WIki, thank you!

magic-lantern commented 5 years ago
  • [x] @magic-lantern are you suggesting here that we add information to the readme that instructs people to do this?

If we are going to have people fork to start their own Abra-Collaboratory based project, then yes, I think steps to enable issue tracking should be documented in the README.md. I'm happy to make that change if you're supportive.

magic-lantern commented 5 years ago

I've updated the README.md to include instructions about enabling issues. I believe everyone that has been asked to review this repository has done so. @callahantiff - can we close this issue?

callahantiff commented 5 years ago

Absolutely @magic-lantern, thank you for the reminder. I still owe you some feedback on a few other issues, which I will respond to by the end of the weekend 😊