Giters

KatherineMichel / setting-up-an-open-source-project

:repeat: Setting Up An Open Source Project

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

documentationopen-sourceplanningtutorial

Setting Up An Open Source Project

Photo Credit: Pete McCarthy

Table of Contents

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.

🔝 back to top

Initial Documentation

README.md

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

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.

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.

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.

.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.

.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."

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).

Teams

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

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.

Projects

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

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.

ISSUE_TEMPLATE.md

PULL_REQUEST_TEMPLATE.md

🔝 back to top

Contributing Documentation

CODE_OF_CONDUCT.md

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

CONTRIBUTING.md

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

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.

🔝 back to top

Helpful Resources

Git and GitHub Documentation

Git Cheat Sheets and Tutorials

GitHub Markdown Documentation

Presentation Tools

Project Funding

🔝 back to top

About

:repeat: Setting Up An Open Source Project

documentationopen-sourceplanningtutorial