Setting Up An Open Source Project

Photo Credit: Pete McCarthy

Table of Contents

• About
• Testimonials
• Documentation File Types
  • Markdown
  • Dotfiles
• Initial Documentation
  • README.md
  • Wiki
  • LICENSE.md
  • Presentation
• Editor Configs, Environment, Git
  • .editconfig
  • .env
  • .gitattributes
  • .gitconfig
  • config.yml
• Build Automation
  • makefile
• DNS
  • CNAME
• Advanced Work Flow
  • Git Flow
  • A Successful Git Branching Model
  • Comparison between Git Flow and A Successful Git Branching Model
  • Semver
• Release Documentation
  • Roadmap
  • CHANGELOG.md
  • RELEASING.md
• Collaboration
  • Organizations
  • Teams
  • Repository Access
• Common Project Contributor Tasks
  • Backend
  • Frontend
  • Support
  • Media
• Workflow Tools
  • Projects
  • Issues
  • Milestones
  • Pull Requests
  • Code Review
  • Repository Statistics
• Contributing Templates
  • ISSUE_TEMPLATE.md
  • PULL_REQUEST_TEMPLATE.md
• Contributing Documentation
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • Styleguide
• New Contributors
• Helpful Resources

About

While looking through GitHub repositories and reading/watching coding tutorials, I have come across a number of best practices for setting up projects. I've never seen these best practices in one place, so I decided to create my own list. Though some are more common than others, a few are obscure, but highly useful! This list is fairly unopinionated. Depending on the language/framework used in a project, additional config files will be needed.

🔝 _{back to top}

Testimonials

“Great idea and that's really useful.”
— Jeff

“Cool :) This looks really useful. I'll have to follow the suggestions there.”
— Mariatta

🔝 _{back to top}

Documentation File Types

Markdown

GitHub project documentation is often created using Markdown files (files that end in .md). Markdown tends to be simpler and easier to use than regular HTML. See GitHub flavored Markdown for instructions.

Dotfiles

Dotfiles begin with a dot and often contain configuration info specific to the developer or project. Dotfiles (or folders) are normally hidden from view.

• Hidden File and Hidden Directory

🔝 _{back to top}

Initial Documentation

README.md

A README is a file that contains project information and instructions.

• Example README Structure

Wiki

A README usually suffices for providing project information. If not, every GitHub repo comes with a wiki. The project wiki is enabled by default under Settings -> Features. Editing can be restricted to collaborators only. GitHub wikis can be created using GitHub flavored Markdown and hyperlinks can be created across pages.

• GitHub Projects with Great Wikis

LICENSE.md

A Software License specifies the terms under which open source code can be used and redistributed. GitHub offers guidance for choosing a license. A repo that does not contain a license is considered copyrighted and therefore cannot be used publicly without permission.

• GitHub Choose a License
• GitHub Open Source Licensing

Presentation

Consider adding a presentation using GitPitch. Create a PITCHME.md using markdown. A presentation URL such as the one for this repo, will be automatically created.

🔝 _{back to top}

Editor Configs, Environment, Git

.editconfig

A .editconfig is a dotfile in which a developer or project maintainers can specify local editor preferences. For example, if developers are working on different operating systems (Linux, Mac OS, Windows), .editconfig settings can be used to standardize line endings across all machines.

• EditorConfig
• EditorConfig Plugins

.env

A .env file is a dotfile used to store environmental variables. Beware pushing a .env file to a public repo. Include the .env in the .gitignore (see below), or, set the environmental variables through the command line/bash or host dashboard.

.gitignore

When running code locally, some files may be generated that are only for your own local use. A .gitignore is a dotfile used to instruct Git to not include these files when pushing code to GitHub, where they would be unncessary. GitHub provides .gitignore templates that vary by language or framework. Alternatively, files to be ignored can be stored in hidden folders named .git/info/exclude.

• GitHub .gitignore Templates

.gitattributes

.gitconfig

A .gitconfig is a dotfile in which a developer or project maintainers can specify local Git preferences.

config.yml

🔝 _{back to top}

Build Automation

makefile

A makefile contains code for build automation.

Earthly

An Earthfile contains code for containerized build automation.

🔝 _{back to top}

DNS

CNAME

A CNAME file is used to specify a domain name.

🔝 _{back to top}

Advanced Work Flow

Git Flow

GitHub Flow is GitHub's "lightweight, branch-based workflow."

• Understanding the GitHub Flow

A Successful Git Branching Model

A Successful Git Branching Model is a popular Git workflow methodology referenced often by professional developers.

Comparison between Git Flow and A Successful Git Branching Model

Scott Chacon, a GitHub developer, wrote in a blog post called "Issues with git-flow" that GitHub Flow is a simple process that can be used to deploy often. In contrast, git-flow (from A Successful Git Branching Model), is a sophisticated process focused on major releases, and may be more complicated than what most developers need.

Startup Engineering MOOC

Startup Engineering MOOC is currently out of commission, but is a highly recommended introduction to staged deployment using GitHub, Heroku, and AWS.

Semver

Semver is a popular versioning methodology used for software releases.

🔝 _{back to top}

Release Documentation

Roadmap

A Roadmap is a schedule for future project goals. A roadmap could be communicated through a Markdown file or through a project.

Project Example

• Project name is version name
• Example columns: To Do, In Progress, Testing, Done

CHANGELOG.md

A CHANGELOG.md file lists notable changes made to the project.

RELEASING.md

A RELEASING.md file gives instructions for how to complete a software release.

🔝 _{back to top}

Collaboration

Organizations

Organization accounts are for code owned by groups (companies, OSS projects).

• About GitHub Organizations

Teams

Teams make permission management easier. A developer added to a team now has access to repos based on team access.

• Setting Up Teams
• Maintaining Teams

Repository Access

• Public repo- anyone can access
• Private repo- only designated members can access

🔝 _{back to top}

Common Project Contributor Tasks

Backend

• Code
• Plugin/utility libraries
• Tools
• Infrastructure (Hosting, Build-Tools, etc)
• Tests
• Bug reports
• Examples
• Translation

Frontend

• Design

Support

• Reviewed Pull Requests
• Documentation
• Answering Questions (in Issues, Stack Overflow, Gitter, Slack, etc.)

Media

• Blogposts
• Tutorials
• Videos
• Talks

🔝 _{back to top}

Workflow Tools

GitHub provides a number of special features that help with workflow.

• GitHub Features

Projects

GitHub projects are a feature that can be used to prioritize and track workflow through a board of columns and cards.

• Projects

Issues

Issues are discussion threads used to ask questions, propose new functionality, and report bugs. Issues can be assigned to people, associated with a milestone, or tagged with one or more labels (which can also be found through GitHub search). Issues that are no longer relevant can be closed.

Example Difficulty Level Labels

• difficulty: easy, difficulty: medium , difficulty: hard

Example New Comer and Help Wanted Labels

• help wanted, up-for-grabs, first-timers-only, beginner friendly

Example General Labels

• question, for discussion, docs, feature, bug, enhancement

Types of GitHub Comments

• On the pull request
• On the commit
• On a line

Commenting Enhancements

• @ mentioning

Mention an issue in a commit and it will show up in the issue and notify anyone subscribed to issue. Include "fixes" "closes" or "resolves to auto close the issue when merged in default branch (probably master)

$ git commit -m "Should help with issue #1"
$ git commit -m "Fixes #1"

Milestones

Milestones are a scheduling tool used to track the progress of activity.

Pull Requests

A pull request is a submission of a proposed change to a code base.

Code Review

Code review is examination of code to determine quality.

Branch Protection

Branch Protection prevents collaborators from making irrevocable changes to the branch.

Repository Statistics

🔝 _{back to top}

Contributing Templates

When an issues or pull request template is added to a repository, the template contents will automatically populate in the issue or pull request form body. These templates can be stored in the root or a hidden directory named .github.

• GitHub Issue and Pull Request Templates

ISSUE_TEMPLATE.md

• Example ISSUE_TEMPLATE Structure
• Creating an Issue Template for Your Repository

PULL_REQUEST_TEMPLATE.md

• Example PULL_REQUEST_TEMPLATE Structure
• Creating an Pull Request Template for Your Repository

🔝 _{back to top}

Contributing Documentation

CODE_OF_CONDUCT.md

A Code of Conduct sets forth the standard of conduct expected of project contributors.

• Adding a Code of Conduct to Your Project

CONTRIBUTING.md

A CONTRIBUTING.md file provides guidance to contributors about best practices for contributing to the project.

• Setting Guidelines for Repository Contributors

Styleguide

Similarly to a journalistic styleguide, a programming styleguide illustrates the project's preferred coding conventions.

🔝 _{back to top}

New Contributors

Ideally, make project welcoming to newcomers, with user-friendly documentation. Include a mentor list, if applicable.

• Helping People Contribute to Your Project

🔝 _{back to top}

Helpful Resources

• GitHub Blog

Git and GitHub Documentation

• Git Homepage
• Set Up Git
• Try Git
• GitHub Help
• GitHub Training
• GitHub Bootcamp
• GitHub Guides

Git Cheat Sheets and Tutorials

• Git and GitHub in Plain English
• GitHub Development Git Cheat Sheet
• GitHub Hello World Tutorial
• Atlassian Git and Atlassian Git Tutorials
• Digital Ocean Git Tutorial Series
• Bitbucket Learn Git with Bitbucket Cloud

GitHub Markdown Documentation

• GitHub Flavored Markdown
• GitHub Mastering Markdown Tutorial
• Enterprise Markdown Cheat Sheet

Presentation Tools

• GitPitch

Project Funding

• Lemonade Stand

🔝 _{back to top}