Skip to content

Instantly share code, notes, and snippets.

@joshgav

joshgav/github_practices.md

Created March 8, 2019 21:49
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save joshgav/d486e43ac4c4396609a964ea0a98ba44 to your computer and use it in GitHub Desktop.
Save joshgav/d486e43ac4c4396609a964ea0a98ba44 to your computer and use it in GitHub Desktop.
Download ZIP
GitHub open project best practices
Raw
github_practices.md

Open source on GitHub: what and why

  • Participants: users, contributors and maintainers.
    • We're looking for users.
    • README.md and CONTRIBUTING.md
  • Why open source?
    • Collect better feedback on our software from users.
    • Gather direct insights into how users use our software.
    • Developers are empowered to:
      1. fix problems and answer questions themselves and maybe even blog about it
      2. open detailed and actionable issues for us
    • Direct channel to product team.
  • Some things don't change:
    • CSS is as important as ever; not all developers want to use GitHub.
    • We'll still use DevOps for work item tracking.
    • CI is provided by DevOps Pipelines.

GitHub Issues

  • Most issues are to ask for help.
    • Issue templates: help users help us.
  • Cross-references and @-mentions help people find related issues and learn.
  • Respond to feature requests too, perhaps with an @-mention.
  • Above all else be patient.
    • We know much more about our software.
    • They might not write English in the way we expect.
    • Most users come around. See e.g. Azure/azure-sdk-for-go#3111
    • Users opening issues are our MVPs.
  • Issues are also a knowledge base for later searchers to provide complete answers.
  • Key Performance Indicators (KPIs):
    1. Time to first response.
    2. Time to resolution.
  • Suggestion: IcM assignee also handles GitHub issues.

GitHub PRs

  • PR templates: help contributors help us.
  • Typical flow is fork then PR rather than branch then PR, because contributors can't push branches.
  • Tests should be included and CI must pass; we can help if needed. This is why we need public CI results.
  • Squash and rebase, but retain the original commit and author!
  • Significant PRs should be assigned to one maintainer for interaction and eventual merge (or close).
  • TODO: establish standards for commit messages.
  • Keep a clean history.
    • Suggestion: don't force-push. Don't change the commit associated with a tag.
    • Suggestion: avoid merge commits by always rebasing.

GitHub Features

Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment