🐱 Kickstart a GitHub Project

Naming

• Repository: Use lowercase¹, and hyphen (-) to separate words. For example, my-awesome-project.

Branching

The default branch should always be main. For existing projects, rename them by following GitHub's instructions and the following command on local machine:

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a
git remote prune origin

Development Flow

For smaller projects, use GitHub Flow. For larger projects, use GitFlow.

Some Pros and cons:

	GitHub Flow	GitFlow
Pros	1. Plain simple, easy to maintain 2. Dev iteration is faster	1. More suitable for large team collaboration 2. Can easily work on different features at the same time.
Cons	Bugs are accidentally merged into main branch more often	1. Maintaining CI on multiple branch can be a nightmare 2. Need to cherry-pick hotfixes to dev/feature branch quite often.

Read more in this article.

GitHub Settings

General > Features

• Wikis: Ues as minimal documentation if project needs one. Consider a dedicated site if project needs more than a few pages.
• Issues: Disable only if project is not open source.
• Sponsorships: Enable if project is offered more or less as a product/service. Use the template from here
• Discussions: Always enable. Use as a forum for users to ask questions and share ideas, and making announcements.
• Projects: Always disable. Use alternatives.

General > Pull Requests

Checks only Allow merge commits, and Pull request title and description as Default commit message.

This is an idea from GitFlow. The main benefit is that you can easily identify which branch a commit came from, and it's easier to revert a feature.

Also checks the following:

• Always suggest updating pull request branches
• Allow auto-merge
• Automatically delete head branches

Because they are useful, and does not yield any downsides so far.

Branches > main

If not mentioned, leave as default.

• Require a pull request before merging
  • Require approvals: 2 is ideal, but 1 is fine too.
• Require status checks to pass before merging
• Do not allow bypassing the above settings

Footnotes

1. Although GitHub supports uppercase, but many package managers and tools do not. ↩