When writing code, it's important to know our general philosophy as a software company, and where the software itself fits in with the bigger picture.

Code exists to serve our product, which exists to serve our customers and users. In other words, our overall priorities as a software company go in the following order:

1. Customer / user
2. Product
3. Code

Put another way: A technical solution that fixes an issue for a real user is far more important than one that is merely technically elegant or “good.” “Done and deployed” is always better than “unfinished but elegant.”

To drive this point home: we are not pursuing technical perfection. We're pursuing perfection of the customer's experience. Code is the means by which we most often get there, but it's not the only way.

With that in mind, it's helpful to follow some guidelines:

In general, take the shortest route possible. This doesn't mean doing things the wrong way, or writing bad code in the name of getting something done. Rather, it means that you should pursue the simplest solution first, even if it doesn't cover 100% of use cases.

What is simplest? It's whatever accomplishes our product and customer goals without excessive re-architecting, unneeded complexity, etc. If a solution has technical shortcomings but accomplishes our product and customer goals (without harming them), it is a good solution.

For any shortcomings, you should note them in commit messages and task trackers, and create new tasks (attached to the original task) to address any issues later, if needed. But, today: ship it.

Solve for today's problems before solving for tomorrow's. It's important to keep our long-term vision in mind whenever developing something new. But your priority should always be to solve user problems that exist today before solving hypothetical ones that might exist tomorrow. Prepare for inevitable change and eventual gotchas as much as possible — but don't let it keep you from shipping complete solutions today.

Keep the big picture in mind. Before starting a task, it's important to know what the product and customer goals are, so you can make the right development decisions on your own. Knowing what our priorities are will help you determine what's important or not, what to focus on, and when you're finished. We hold all team members to this high standard, so everyone is aligned on our mission of building some of the best software products in the world.

If you're ever unclear about the larger vision, goals, and strategy, ask us until everything is clear. If you don't understand why we're doing something, making certain decisions, etc., then that's a failing on our part.

Make multiple, granular commits. Work on small, concrete pieces of the task at hand. Then, when you've completed a usable chunk of code, use git add -p to step through your changes and commit only the ones that complete that certain bit of functionality. Often, this will result in creating multiple commits — even very small ones. That's okay!

Small commits make everyone's lives easier, from other developers to regular people scanning through the code. Doing so:

• Makes it easy to read through a log of changes in plain English, and quickly understand the decisions made over time without having to dig into code
• Makes it easy to use the git blame tool, to figure out why a certain change was made when looking it up from a line of code
• Makes it easy to revert decisions for any reason. Rather than the error-prone process of going into the code and undoing your changes, you can just do git revert [commit-hash]

Some examples of granular commits:

Fix file indentation
Run goimport on project
Fix Docker build after enabling Go modules
Include --config step in `make install`

Write good commit messages. Once you've started making granular commits, you'll want to ensure their messages are easy to understand and consistent with the rest of the project.

The first line of your commit message should concisely sum up the changes in your commit, ideally in under 75 characters. If that's not possible to do, that could be an indication that your commit contains too many unrelated changes, and should be broken up.

As for how to write the commit message, follow the advice given in the Git book:

Write your commit message in the imperative: “Fix bug” and not “Fixed bug” or “Fixes bug.”

After that short, initial line in your commit message, you can optionally explain your changes in more detail below it. That may include:

• Rationale for any decisions made
• What other parts of the software are affected by the change
• What existing behavior changed
• References to GitHub issues, e.g. Fixes #19 or Part of #13, or Phabricator tasks, e.g. Fixes T123 or Ref T234

Don't force-push. Force-pushing creates headaches for other developers when they pull your code. Instead of force-pushing, create new commits, revert commits, and generally use the other git tools available to you to accomplish what you need to.

• Make sure your development environment is set up (e.g. if you're working on WriteFreely, make sure Go is installed, and you can run the application)
• Check out the develop branch with git checkout develop
• Create a new feature branch with git checkout -b my-feature
• Start working on the feature

Read our guide on good Source Control habits. Overall:

As you go along, track your time, make granular commits (where each represents a single chunk of functionality), and write decently descriptive commit messages (ideally, using the imperative present tense). When a commit relates to a specific task, you can include Ref T500 (where 500 is the task number) in the commit message to associate it to that task.

When the functionality is ready for review, open a pull request on the related GitHub repo. Matt and others will look over the code, run it, and give you feedback — requesting any changes, if needed. While a pull request is open, anyone should feel free to test it out and give their input. Then when everything looks good, we'll merge your change.

Code style

We aim for consistency first and foremost. Try to match the code styles (line breaks, indentation, etc.) currently used in the codebase. Where styles are inconsistent, use the one that seems to be most prevalent.

When writing Go, please run go fmt on all files before committing them. The best way to ensure this happens consistently is to use an editor tool that runs this command every time you save the file (for example, vim-go takes care of this, if you're using Vim).

First steps

First, we need to take care of the paperwork:

1. Add your address and sign the Consulting Agreement
2. Fill out and sign a W-9 form
3. Send us those documents

Note: with a signed Consulting Agreement, you do not need to sign the CLA to contribute to WriteFreely, as is required of general contributors.

Now that all the paperwork is taken care of:

1. Create a Phabricator account — this is where most of our work will happen.
2. Once we approve your account, have a look around. We'll mostly be using the chat (“Conpherence”) and task-tracking features (“Maniphest”).