• Stars
    star
    144
  • Rank 250,404 (Top 6 %)
  • Language
  • Created over 3 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

how to use this dang site!

I think there are a bunch of resources out there that go totally wild with a specific branch setup or whatever, but are less about the system as a whole and often are sort of uniformly opinionated.

Here are some things I think make sense as recommendations. Read them as geared toward a long-lived, continuously-deployed product, like a web application or API.

These recommendations are opinionated. But they're not fancy or extreme. A lot of teams probably already do something like this.

Branches

Opinionated: don't branch off a branch off a branch

There's the main branch, called main or master. And then there are feature branches. And every once in a blue moon, you want a branch that refers to a feature branch.

A good example is if someone puts up a PR and someone else decides that, instead of giving extensive PR feedback, they might as well just suggest all the changes and improvements they see are necessary. You can do a little of that with GitHub's suggestions system in PRs, but it's kind of limited.

But don't go beyond that. Don't create feature branches on feature branches on bug branches. Any kind of branch structure more than one step deep gets incredibly hard to review, maintain, and merge. If a feature relies on some other feature, either work on them in the same branch, or merge one branch and them create a new branch from main.

Unopinionated: branch naming

I see no reason to be picky about branch names. Put your username in them, or make them jokes, make them descriptive, put issue numbers in them. I haven't seen it matter ever: branch names can't contain that much information, they're not highlighted in the GitHub UI, and they shouldn't last long anyway.

Naming your "main" branch branch on the other hand: name it main by default. If it's already called "master" because you created the repo a while ago, name it main if you think that's important.

Unopinionated: it really doesn't matter if you delete branches

Some people are careful to delete branches after Pull Requests are merged, and some aren't. GitHub has added some additional magic on top of git so that you can delete a branch from a repository but then recover it.

Deleting branches is useful for the pretty rare case where branch names conflict - you work on something locally git push origin it, and the repository already has a branch with that name. That seems pretty rare, and you can just delete the branch then, if you want. Whether you delete branches or not doesn't seem to matter enough to make a rule.

Tests

Opinionated: if you have tests, your main branch should always pass them

Failing tests should be an absolute veto for any pull request. Tests can fail in development branches, but there should be no period during which the main branch of your repository has failures in the test suite. If it fails because of flaky tests, the reasons for non-deterministic test behavior should be pinned down and solved.

Issues & Milestones

Opinionated: everything has a description

Write your issues and pull requests so that other people know what's going on. Issues or PRs that lack descriptions are bad and should be avoided always. Understand the curse of knowledge and avoid it.

A really great sign of someone who gets it is that they'll have some open source repository and even though it's just them, talking to themselves, they write great issue descriptions.

Opinionated: Pull requests reference issues

All but the tiniest changes should be written down in an issue before anyone creates a PR. Those PRs should reference the issue, and, ideally close that issue with a Fixes reference.

Issues that are too big to be fixed by a single PR may be too big and should be split up into smaller issues.

This serves a few different purposes. By creating an issue first, others might catch mistaken ideas. If you're planning on writing a PR but never get around to it, the issue crystalizes your intent so that others can pick up the same work later on. If the PR doesn't do the trick, the issue serves to track future work and future PRs that try to solve the same problem.

Project management

Unopinionated: "Projects view" for individual repos

The Projects view for individual repos gives a Kanban view of the work being done. This can be nice for project managers, but tends to have no effect on developers and designers.

At best, the Projects view is just another view into the issues: it's automated, so that issues move from place to place when PRs solve them.

The projects view is a problem if it starts to work as a parallel to issues, and people create notes in Projects that really should be issues.

Opinionated: use milestones for bounded chunks of work and labels for categories. Do not mix them.

  • Labels are for categorical information. A good label is "bug", or "feature".
  • Milestones are for chunks of work with dates attached. A good milestone is "New feature sprint".

Milestones are useful because they have progress bars and dates. Labels are useful because they're easily searched, color coded, and multiple labels can apply to the same issue.

Do not use milestones for categorical information: if you create a milestone of "bugs" or a milestone of "UI", the progress bar will never reach 100%, and you won't be able to use the "deadline" feature of milestones, because those things are, by definition, unbounded.

PRs

Unopinionated: squash, merge, and rebase

All different ways to "merge a PR". Technically, merge and rebase can give you more truthful git history, and squash can give you better semantic git history. But practically, git history rarely really matters in long-lived projects, and sufficiently wacky local git habits will ruin any history.

Time spent on fancy git moves is usually better spent doing something else.

Opinionated: PR authors should be the one to merge their PRs

Obviously, if only some users have the ability to commit to a repository, then they have to merge other people's PRs.

But in the common setup: technically anyone in a normal GitHub repo can merge any PR. So who should? The PR author is the most practical answer. If the repository does continuous deployment, this makes the person overseeing that automatic deploy the same person with knowledge of what new code is being deployed. If the tests fail as soon as the PR is merged, the PR author is the one responsible for fixing them, and so on.

There are exceptions, of course - if folks are out of the office, or a PR needs to be merged in a hurry, or something else. But the best norm is: author merges.

Opinionated: small, fast, single-idea pull requests

Pull requests are ideally short, don't stay open for longer than a few days, and capture a single idea. Gigantic requests aren't easily reviewed and have the tendency to cause chaos when they get merged - causing conflicts for other PRs, making it hard to hunt down the root cause of any new regressions.

Some ideas are big, so their pull requests can't be that short. But at least focus on capturing a single idea. PRs shouldn't mix routines like code formatting or cosmetic tweaks with new feature development. They shouldn't include a bugfix in one part of the code, and a feature in another. If you notice something that you want to do while writing a PR, that doesn't fit into the idea of that PR, open an issue or create a separate PR for it. Don't combine multiple ideas into the same chunk of work.

Commits

Opinionated: commit often

Don't keep lots of work in your local copy of the code: commit and push it to GitHub, continously. If you do a chunk of work - a half hour or an hour, and you're walking away from your computer to make coffee, commit your code. If you finish a part of a feature, commit your code. Commits are free - you can make a lot of them.

I've encountered several instances where people will wait to commit their code until it's nice and cleaned up. This is an instinct that people should avoid. A coworker might create a helpful branch with fixes for the work that's on GitHub, but then when it's time to accept those changes, you realize that you've already changed that file, deleted it, or made the fix yourself. There's also some chance that you'll lose your computer before pushing that commit, or realize that you made a mistake halfway through a project and want to revert to an earlier point in time. If you just do one "big-bang" commit with all the code, this doesn't work.

The code on GitHub should, as much as possible, be the same as the code on your computer. It's okay if the code isn't perfect all the time: refining, publishing, and accepting code is the job of pull requests, not commits.

Opinionated: commit messages should be meaningful

Other people think that commit messages must be sentences in the present tense with x, y, and z. Perhaps, but I think it's more important that commit messages just aren't terrible. So no commits like "updating file.js". But "Fixing dotheFunction off-by-one" is a pretty decent commit message.

Tools that commit for you, and create characteristically terrible commit messages by default, are becoming popular. This is, of course, bad. And in that case, it's vital to use squash or rebase to rewrite those bad commit messages into something a a little more useful.

But individual commit messages don't need to be some sort of fine art: the best tool for understanding changes in a repository is the Pull Request that commit came from, which, per the previous advice, better have a well-written description.

Documentation

Opinionated: use readme files in the repository for documentation

Core documentation shouldn't live in a wiki, or Notion, or somewhere else: it should live in the repository, alongside code, in Markdown. This helps make it clear which documentation belongs to which point in time. Wikis easily fall out of date, and documentation that isn't in the repo won't get downloaded with the repo.

Try to keep it simple. Fancy tools for writing exist, but plain-text or Markdown should be the format of the vast majority of developer documentation.

Content

Opinionated: don't put big binary files in git

Git, by itself, is not a good system for managing binary files. If you use it to store your Photoshop or data files, the size of your git repository will rocket and it'll be slow to clone it and sometimes even hard to store it on your hard drive. Git keeps all the versions of everything, and is not efficient at doing that with big binary files.

If you want to version large files and keep them in a repository, use Git LFS and configure it to store the kinds of large files you'll be managing. This will save you from the inefficiency and risks of big binaries in Git.

Otherwise, if the files don't need to be versioned or stored in Git, you can use releases, or an external file storage system like S3 to store them.

More Repositories

1

big

presentations for busy messy hackers
JavaScript
3,268
star
2

awesome-geojson

GeoJSON utilities that will make your life easier.
2,084
star
3

docbox

REST API documentation generator
CSS
1,136
star
4

mapmakers-cheatsheet

popular tourist destinations on the wild and exciting quest to make web maps in fewer tries
411
star
5

stickshift

A clean & modern SQL data interface.
JavaScript
373
star
6

systemfontstack

HTML
288
star
7

literate-raytracer

a literate raytracer in javascript
HTML
193
star
8

wah

a slightly higher-level language superset of webassembly
Clojure
150
star
9

geojson.net

JavaScript
150
star
10

perception

collected & summarized research on the effectiveness of visualization techniques
148
star
11

gedcom

A simple GEDCOM parser that focuses on translating GEDCOM structure into JSON.
TypeScript
145
star
12

wcag-contrast

WCAG contrast ratio measurement and scoring
JavaScript
120
star
13

notfoundbot

fix & archive outgoing links on your website
TypeScript
109
star
14

mistakes

line-oriented presentation-optimized live coding in javascript
JavaScript
108
star
15

happen

make real events happen in-browser, with pure DOM and optional $
JavaScript
105
star
16

biggie

everyone can get big
JavaScript
104
star
17

simpleopendata

simple guidelines for publishing open data in useful formats
HTML
89
star
18

flair

Cocktail browser interface and dataset
Elm
81
star
19

geojson-random

Generate random GeoJSON features.
JavaScript
73
star
20

d3-axis-for-react

d3-axis for React
TypeScript
63
star
21

minute-agent

a keycounter for osx
Objective-C
57
star
22

heard

a minimal, local listener for iTunes data.
Objective-C
53
star
23

geojson-flatten

flatten multipart geometries and geometrycollections in geojson
JavaScript
50
star
24

today-i-learned

keeping track of things i never would have guessed but were true anyway
45
star
25

running-for-nerds

like running, but for nerds
42
star
26

react-tangle

A tangle.js-style numeric input for React.js.
JavaScript
39
star
27

node-canvas-animation-example

An example of how to use node-canvas to create an animation as a GIF and a Video
JavaScript
38
star
28

presentations

Presentations I've given
JavaScript
36
star
29

minute

a personal data visualizer
JavaScript
36
star
30

quotes

guiding principles.
34
star
31

stickshift-app

Stickshift as a desktop application.
JavaScript
33
star
32

sitemap-static

Make a sitemap for a static website based on files on disk
JavaScript
31
star
33

testing-webgl

Notes on continuous-integration testing WebGL applications and libraries.
30
star
34

togeojson-cli

toGeoJSON in the console
JavaScript
28
star
35

nvim

My .vim
Lua
28
star
36

dx-spec

Issue (and spec) repository for the development of a spec that would succeed JSDoc.
27
star
37

relative-luminance

Calculate the relative luminance of an RGB triplet color.
JavaScript
27
star
38

coffeedex

openstreetmap but for coffee
JavaScript
27
star
39

make-relative

JavaScript
26
star
40

windchime

assistive / ambient technology for writing software
Objective-C
26
star
41

d12

documentation future experiment
JavaScript
25
star
42

bespoke

Image resizing for macwright.org. Full, medium, small, and original, in jpeg and webp.
JavaScript
25
star
43

sometimemachine

openstreetmap history analysis
HTML
23
star
44

obsy

livecoding observable-ish experiment, just an experiment
JavaScript
22
star
45

k-means

k-means clustering
JavaScript
21
star
46

fischer-color

eric fischer's perceptually-friendly color system
JavaScript
20
star
47

memory-geojson

experimental memory-efficient geojson representation
JavaScript
19
star
48

bookish-api

bookish api
JavaScript
18
star
49

canvas-animation-maps-example

http://www.macwright.com/2015/08/31/canvas-animations-on-maps.html
JavaScript
18
star
50

openstreetmap-landscape

writing about mapping is like dancing about architecture
17
star
51

trump.mistakes

HTML
16
star
52

visualization-cheatsheet

data β‡’ representation
16
star
53

ditty

JavaScript
15
star
54

pig

pig is a presentation system for beautiful people
JavaScript
14
star
55

awesome-coding-paradigms

14
star
56

myland

Scraping and displaying TrafficLand data.
Python
13
star
57

projectityourself

a website that encourages people to make their own projections
JavaScript
13
star
58

geos-wasm

C
13
star
59

bookish

JavaScript
13
star
60

zig-raytracer

a webassembly/zig raytracer
Zig
13
star
61

literate-game-of-life

a literate javascript implementation of conway's game of life
CSS
12
star
62

identify-hate

identifies hate groups on GuideStar
JavaScript
12
star
63

landpatch

a visualization of landsat collection paths through the northern hemisphere
JavaScript
12
star
64

the-united-states-of-america

12
star
65

dcmr

making the DC Municipal Regulations Accessible
JavaScript
12
star
66

running

acquiring, processing, and visualizing running data
Python
11
star
67

big-themes

themes for big
JavaScript
11
star
68

truisms

truisms for your lock screen
EJS
11
star
69

shotspotter

gunshot data from shotspotter
JavaScript
10
star
70

clone-pull-requests

re-file pull requests from one repository to another
JavaScript
10
star
71

are-we-flow-yet

A CLI tool that scans a source directory and gives statistics and a big list of files that are and are not flow-annotated.
JavaScript
10
star
72

incremental-eval

run javascript line-by-line
JavaScript
9
star
73

deuteranopia

Simulate the prevalent deuteranopia form of colorblindness.
JavaScript
9
star
74

bookish-old

semi-universal book identification code converter
JavaScript
8
star
75

got-links

download multiple pages of results from a paged endpoint
JavaScript
8
star
76

treeui

A simple collapsible tree ui, for file selectors and the like.
JavaScript
7
star
77

dc-ownership

Tinkering with Real Estate ownership and assessment data.
Go
7
star
78

exif-extract

extract exif data from files dropped, including positions and thumbnails
JavaScript
7
star
79

orphanarium

Find non-required files in your source tree.
JavaScript
6
star
80

live-require

simple script-tag includes
JavaScript
6
star
81

demo

lightweight demos
JavaScript
6
star
82

howsmy

Python
6
star
83

awesome-converters

just a list of the tools for converting things
6
star
84

rust-geojson-random

Rust
5
star
85

gandi-ipfs

JavaScript
5
star
86

lodebuilder

loading gif builder
JavaScript
5
star
87

coords

parse and generate decimal and sexagesimal latitude longitude coordinates
JavaScript
5
star
88

taurus

Swift
5
star
89

channel-arc

HTML
4
star
90

flacbox-sync

JavaScript
4
star
91

snap-archive

archive a specific geographical area of snapchat posts
JavaScript
4
star
92

entropy

research into random
4
star
93

ukulele

The code to uke.tommacwright.com
Ruby
4
star
94

podcast-luddite

Shell
4
star
95

stories

narrative-specific open data or accessibility projects
Elm
4
star
96

turtle

turtle, on the internet
JavaScript
4
star
97

terrarium-stream

an interface to terrarium that provides a readable & writable stream
JavaScript
3
star
98

geo-codepoints

generates sets of unicode codepoints for each square on the earth
JavaScript
3
star
99

teenmom

a band, a plan, a nalp
CSS
3
star
100

npm-add-repo

Add a repository field to a package.json that doesn't have one.
JavaScript
3
star