- About
- Testimonials
- Documentation File Types
- Initial Documentation
- Editor Configs, Environment, Git
- Build Automation
- DNS
- Advanced Work Flow
- Release Documentation
- Collaboration
- Common Project Contributor Tasks
- Workflow Tools
- Contributing Templates
- Contributing Documentation
- New Contributors
- Helpful Resources
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.
“Great idea and that's really useful.”
— Jeff
“Cool :) This looks really useful. I'll have to follow the suggestions there.”
— Mariatta
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 begin with a dot and often contain configuration info specific to the developer or project. Dotfiles (or folders) are normally hidden from view.
A README is a file that contains project information and instructions.
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.
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.
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.
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.
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.
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.
A .gitconfig is a dotfile in which a developer or project maintainers can specify local Git preferences.
A makefile contains code for build automation.
An Earthfile contains code for containerized build automation.
A CNAME file is used to specify a domain name.
GitHub Flow is GitHub's "lightweight, branch-based workflow."
A Successful Git Branching Model is a popular Git workflow methodology referenced often by professional developers.
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 is currently out of commission, but is a highly recommended introduction to staged deployment using GitHub, Heroku, and AWS.
Semver is a popular versioning methodology used for software releases.
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
A CHANGELOG.md file lists notable changes made to the project.
A RELEASING.md file gives instructions for how to complete a software release.
Organization accounts are for code owned by groups (companies, OSS projects).
Teams make permission management easier. A developer added to a team now has access to repos based on team access.
- Public repo- anyone can access
- Private repo- only designated members can access
- Code
- Plugin/utility libraries
- Tools
- Infrastructure (Hosting, Build-Tools, etc)
- Tests
- Bug reports
- Examples
- Translation
- Design
- Reviewed Pull Requests
- Documentation
- Answering Questions (in Issues, Stack Overflow, Gitter, Slack, etc.)
- Blogposts
- Tutorials
- Videos
- Talks
GitHub provides a number of special features that help with workflow.
GitHub projects are a feature that can be used to prioritize and track workflow through a board of columns and cards.
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 are a scheduling tool used to track the progress of activity.
A pull request is a submission of a proposed change to a code base.
Code review is examination of code to determine quality.
Branch Protection prevents collaborators from making irrevocable changes to the branch.
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.
A Code of Conduct sets forth the standard of conduct expected of project contributors.
A CONTRIBUTING.md file provides guidance to contributors about best practices for contributing to the project.
Similarly to a journalistic styleguide, a programming styleguide illustrates the project's preferred coding conventions.
Ideally, make project welcoming to newcomers, with user-friendly documentation. Include a mentor list, if applicable.
Git and GitHub Documentation
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
Presentation Tools
Project Funding