Add best practices and style guidelines

[sarahhodne]

I sent out a team-wide email about this a little while ago, and decided to start working a bit on this.

From that email:

These last few days I've been thinking that it may be a good idea for us to start writing some best practices for our apps.

Having a set of best practices would make it easier to do things like setting up new projects, or working on a project that you're not that familiar with. An example of what I think of as a "best practice" is us using gemspecs to handle dependencies.

I suggested adding a coding style guide to travis-core a few months back, but it wasn't added due to concerns that it would add unnecessary friction to contributing. I understand why that is a concern, but I still think what I am suggesting is a good idea.

I see how having “rules” for contributing makes it a bit harder to contribute, since you have to follow them and familiarize yourself with them before contributing. However, making sure that new code that is added follows the same “rules” as the code around it means that the code is more likely to look familiar and maintaining the code would be easier.

In the interest of keeping this e-mail somewhat short, I won't be giving more reasons for why I think having best practices written down is a good idea in this e-mail, although I am happy to discuss this further over e-mail or a hangout if you want to.

Here's what I'd like to do: Draft up a set of best practices that describe how most of our current codebase looks. It can then be submitted as a pull request to travis-ci/travis-ci (alternatively travis-pro/ops, although I think we should aim towards making this a public document at some point as it affects OSS contributors too). We can then discuss what exactly we think should be in the document(s).

There are several things I'd like to get feedback on here.

• Do you think we should have anything like this at all?
• Do you think we should have more/less sections? What sections would you like to see/not see?

Pretty much all of the entries in this is taken from Thoughtbot's guides, but I've tried to modify them whenever the practice inside of Travis is different. In general, especially for the style guidelines, I don't think the exact style matters that much, it's more important to be consistent. If you see something that we do differently, or there's an entry you don't understand why is there, or you disagree with it, please leave an inline comment.

And a last question to Travis CI contributors or people who think they might contribute to Travis CI: What do you think of this? Will this make it harder for you to contribute? How could we make sure that contributing is still a smooth process?

I'm happy to talk about this over other media as well, such as Skype or Google Hangout, although I would like to at least summarize the content here to allow more people to comment on it as well.

[sarahhodne]

One thing I'd like to see added to this as well: More Travis-specific things. Right now most of these are very general guidelines, but I'd like to see things like when/how to use things in travis-support, how we deploy, etc.

[roidrage]

I'm in favor of these in general, but I'm rather hesitant regarding coding guidelines. My ideal formatting guideline has four to five rules. Beyond that, people will break them anyway, and they put the focus more on trying to conform to the guidelines than focus on code.

[sarahhodne]

A comment on why Airbnb has a style guide: airbnb/javascript#102 (comment)

FWIW, I still think having a style guide is a good thing, but only if it is actually enforced.