Best practices in using GitHub

[shapaklyak]

Guide users on best practices

• when to start a repository, etc.

[achafetz]

First round. Will clean up and flesh out later this week and create a md file to go in our documents folder.

---

GitHub Best Practices

• Each repo should be its own project
• Commit early and often
• Don’t commit data that isn’t public
• Document, Document, Document
• Install a Git client
• Fork > Clone > Pull
• Utilize Markdown
• Keep your repo and issues up to date and clean

[achafetz]

teaser training "poster"

[shapaklyak]

can we also discuss what to do about existing repos? would we consolidate them based on the new guidance or what would be the best step forward?

[abeagedew]

This sounds great, I am available tomorrow (4/11) or Thur (4/12) morning.

[shapaklyak]

let's use this space as brainstorming ideas until we can have a conversation about it.

things to add:

• use the GitHub projects classification to track issues related to one project; for example, tag all issues related Panorama Requests under BI project; another option for DIV, would be to create Projects by Sprints...so we have the April 3-16 sprint (#64) that could be made into a project for ease of tracking and completion of related tasks. although this may be in contradiction with your earlier point on each project being a repo...

should eat "best practice" bullet also explain how to do it?

@kschlenker @abrahamagedewICPI @achafetz thoughts?

should we start this on a wiki page instead?

[achafetz]

(very) initial draft of best practices stored in Best Practices folder.

Meeting scheduled for Thurdsday at 11:30am

[abeagedew]

Here is my proposed approach in organizing the repos by ICPI Clusters and select few unique activities i.e. RPM, COP, etc. Structuring the repos this way will help us create projects across multiple repos for cross-cutting tasks and activities by creating epics (with common objectives) and further breaking down into detailed issues/tasks. Lets discuss this in detail during our meeting.

[jaliasd]

Hi Abe,

How are projects defined here? Is that a github-project or just a project like a task or somethign that the ICPI works on?

My issue with this is that I feel like assumes that github will be used only as a ticketing system where we want to use it to store and collaborate on code as well. With the way it's structured now, and with what's proposed, forking the entire DAQ repo (with however many projects' worth of code it contains) becomes complicated and messy compared to just being able to fork one project's repo.

Below is more inline with what we are thinking. We'll use the time on Thursday to get into the details of what I describe above so that everyone is on the same page vis a vis the requirements ICPI has for github.

On Wed, Apr 18, 2018 at 10:24 AM, Abraham Agedew notifications@github.com wrote:

Here is my proposed approach in organizing the repos by ICPI Clusters and select few unique activities i.e. RPM, COP, etc. Structuring the repos this way will help us create projects across multiple repos for cross-cutting tasks and activities by creating epics (with common objectives) and further breaking down into detailed issues/tasks. Lets discuss this in detail during our meeting. [image: git_workflow_20180417] https://user-images.githubusercontent.com/18145327/38938032-9ded89ee-42f2-11e8-8c2a-4f8c3f3526f7.jpg

— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/ICPI/DIV/issues/42#issuecomment-382404873, or mute the thread https://github.com/notifications/unsubscribe-auth/AIbWTYBhym7F8pKOQaKZlin6whIeXl96ks5tp0yMgaJpZM4SuUg9 .

-- Joshua Davis, MSPH Senior Strategic Data Analysis Advisor / USAID team co-lead Strategic Information, Evaluation & Informatics USAID Bureau for Global Health | Office of HIV/AIDS Interagency Collaborative for Program Improvement (ICPI) jodavis@usaid.gov 571.243.9720

M T Th F : ICPI / OGAC Wed: CP3 -- Joshua Davis, MSPH Senior Strategic Data Analysis Advisor / USAID team co-lead Strategic Information, Evaluation & Informatics USAID Bureau for Global Health | Office of HIV/AIDS Interagency Collaborative for Program Improvement (ICPI) jodavis@usaid.gov 571.243.9720

M T Th F : ICPI / OGAC Wed: CP3

[abeagedew]

@jaliasd, projects in the above diagram are defined as all activities and tasks that ICPI works on. The only concern I have in creating project based repos is that the ICPI GH space will be extremely messy if folks start creating repos for the projects that they are working on (I get that ppl would need to fork the entire repo and update only the files that they are working on but I believe that is a minor setback). I think project repo structure works if we only had very few projects or if ICPI activities were product based. Limiting the number of repos by Cluster and specialized activities will allow for a more structured approach and also allow the utilization of github projects (and code folders/subfolders by ICPI project) to easily manage tasks and activities to collaborate across repos/clusters. Below is how we are currently organizing the DAQ repo, we have epics for projects and subtasks and also issues to track specific projects. Please note that the epics are pointing to multiple repos (in this case DAQ and Training Dataset repos).

[achafetz]

let's put a pin in this conversation until we meet tomorrow, but let's take this time to think about what our asks/requirements are versus how GitHub is structured and it's purpose.

[achafetz]

During our meeting today, we decided to set aside the broader best practices for GitHub and really focus on the question of when to create a repository. See the best practices document posted to the Documents folder and please provide commit any edits/comments/feedback to the md file. :checkered_flag:

@shapaklyak @abrahamagedewICPI @jaliasd @jb3436 @kschlenker

[jb3436]

@achafetz , I suggest highlighting this (with a screenshot perhaps and a link) during the inbrief.