Democratizing

Project Guidelines

Daniel Li

24 May 2018

Engineering Happy Hour

What is a Project Guideline?

A set of rules that contributors should follow for a project.

It may include:

```
Coding / Style Conventions
```
```
Git Workflows
```
```
Project Management Workflows
```
```
Infrastructure / Deployment Workflows
```
```
Other Best Practices
```

Why?

Everyone comes from different backgrounds.

```
Personal Preferences
```

Workflow carried forward from previous company

Inconsistency == Ineffectiveness

Inconsistent Code Style -> Harder for others to read your code

Inconsistent Git Workflow -> Uncertainty about the status of the project. More merge conflicts.

Give Us Some Examples!

https://github.com/airbnb/javascript

Marketplace for Vacation Homes

Airbnb

https://github.com/mono/website/blob/gh-pages/community/contributing/coding-guidelines.md

Open-source implementation of .NET

Mono

Give Us Some Examples!

https://github.com/elsewhencode/project-guidelines

Technology Design Studio in London

Elsewhen

https://github.com/atom/atom/blob/master/CONTRIBUTING.md

Open-source code editor

Atom

Why Make Our Own Guidelines?

If people have made other guidelines. Why not use those?

There's no best practices that works for everyone

It's hard to get everyone in the team to agree on which guideline to adopt

Why do it democratically?

Team leads can dictate + impose guidelines for others to follow. So why the democracy?

Efficiency - in the short run, to adopt a new standard takes time and can slow down development. So we should find a compromise that works well enough for everyone.

Morale - allow contributors to argue for their point of view

Engagement - Involving contributors into the process increases their engagement

Better Outcome - discussions are valuable way to learn from others

How to do it democratically?

Git, Issues and Pull Requests

How to do it democratically?

```
To discuss something - raise an issue
```
```
To change something - create a PR
```

Any discussion / feedback are done on the issue / PR comments

After agreement is reached, approve or reject the issue / PR

If accepted, the issue / PR is assigned to the person responsible for making the change

Why Git + GitHub?

Transparency - the rationale is documented as comments and commit messages, and can be referred to if a similar argument arises again

Open + Inclusive - Issues and PRs can be openly-discussed. Everyone can be involved, even if they're working remotely.

Encourage Engagement - participation means you can make your own life easier

Aggregate Issues - issue tracker allows you to collect issues to dicuss, altogether, in one effective meeting, instead of many ineffective meetings, one for each issue.