Further contributing updates

Author: bcmn

CONTRIBUTING.md

@@ -1,56 +1,58 @@
-##Contributing to the unofficial WWDC app for macOS project
+# Contributing to the Unofficial WWDC app for macOS Project
 
 Thanks for your interest in contributing to the project. Please make sure you follow the guidelines to maximize the chances of your contribution being accepted.
 
-##1. Issues
+## 1. Issues
 
 Here are the main reasons you might want to open an issue:
 
-####I. Bugs
+#### I. Bugs
 
 When the app behaves in an unexpected way or simply breaks, please file a bug report and describe what you were doing when the problem occurred, what was the expected result and what was the actual result.
 
 Remember to include the version of the operating system you're running and the type/model of the machine (MacBook Mid 2009, iMac Late 2012, etc).
 
-####II. Crashes
+#### II. Crashes
 
 If you get a crash please open an issue and explain what you were trying to do when the crash happened, include a video or screenshots of the problem if possible.
 
 Remember to include the version of the operating system you're running and the type/model of the machine (MacBook Mid 2009, iMac Late 2012, etc).
 
-####III. Feature Requests
+#### III. Feature Requests
 
 If you want a new feature to be implemented, you can open an issue explaining why the feature would be useful to you and to other people.
 
-Keep in mind that we try to keep the app focused and exotic features or features which would add too much complexity to the code may be rejected.
+Whilst we want feature requests and suggestions to be as ambitious as possible, keep in mind that we try to keep the app focused, and niche features or features which would add a lot of complexity to the codebase may be rejected. If in doubt, it's better to suggest it than stay silent!
 
 #### Issue template
 
 Please follow the issue template provided when opening your issue, especially if it's a bug report.
 
-##2. Code (Pull Requests)
+## 2. Code (Pull Requests)
 
-**Important: pull requests that only contain refactoring of existing code without fixing any bugs, improving performance or implementing a new feature will not be accepted.**
+**Important: pull requests that only contain refactoring of existing code without fixing any bugs or linting messages, improving performance or implementing a new feature will not be accepted.**
 
-####I. Tip: Ask before you code
+#### I. Tip: Ask before you code
 
-It has happened a couple of times that we were working on a feature and someone opened a pull request implementing that same feature. This wastes time and effort because only one of the solutions will actually be used, so before you start coding I suggest you take a look at the open issues to see what's being worked on at the moment. If an issue already has someone assigned to it, don't start working on an implementation. It's also important to open an issue before working on a new feature if it's not already listed, because not every feature fits our vision of the app and we like to review feature ideas before implementing them.
+There have been a couple of times that we were working on a feature and someone opened a pull request implementing that same feature. This wastes time and effort because only one of the solutions can ultimately be used, so before you start coding we suggest you take a look at the open issues to see what's being worked on at the moment. If an issue already has someone assigned to it, don't start working on an implementation. If for some reason it's unclear whether they have made any progress or have time to continue, there's rarely any harm in asking.
 
-If you see an open issue and you want to fix it, reply to the issue announcing that you're going to work on it so other people know there's someone already working on that.
+It's also useful to open an issue before working on a new feature if it's not already listed, because not every feature fits our vision of the app and we would rather communicate this before someone spends a significant chunk of time working on it.
 
-####II. Use Swift
+If you see an open issue and you want to fix it, reply to the issue announcing that you're going to work on it so other people know there's someone already working on that. Similarly, if you ever need any help or guidance implementing something then adding a new comment to the issue will help us spot it quickly! We're a friendly bunch.
+
+#### II. Use Swift
 
 All new code in the app should be written in Swift using the latest stable version of Xcode.
 
-####III. Use spaces instead of tabs
+#### III. Keep indentation and style consistent
 
-Do not start a war over this, I don't even have an opinion about this, I just use spaces because I contributed to some project once and people told me I had to use spaces, so I changed the setting in Xcode and never thought about it again, I have much more important stuff to worry about 🙄
+And yes, this means spaces instead of tabs. 😉 It's not worth starting a war over this -- we're not strongly opinionated about it! We just have a clear precedent in the codebase that isn't worth uprooting years into the project -- it simply leads to noisier diffs.
 
-Here's how my Xcode indentation preferences are, please use the same settings when working on this project:
+Here's how our Xcode indentation preferences look -- please try to use the same settings when working on the project:
 
 ![indentation](screenshots/indentation.png)
 
-####IV. Use `guard` and `return` early whenever possible
+#### IV. Use `guard` and `return` early whenever possible
 
 Instead of doing something like this:
 
@@ -90,7 +92,7 @@ func doSomethingIfNeeded(mustCallThis: (result: String) -> ()) {
 }
 ```
 
-####V. Avoid magic numbers and magic strings
+#### V. Avoid magic numbers and magic strings
 
 If you need to reference specific numbers or strings, encapsulate them in `struct`s or `enum`s.
 
@@ -141,24 +143,29 @@ class ImagesViewController: NSViewController {
 }
 ```
 
-####VI. Test your code thoroughly and follow linting rules
+#### VI. Test your code thoroughly and follow linting rules
 
 When you think you're done with your contribution, try to break your code in as many different ways as possible to make sure your implementation is solid:
 
-- If you change something related to the handling of user or application data (model layer) make sure to test the migration of data from a previous version of the app to your modified version.
-- If you change a component related to networking, use the network link conditioner and test with a slow/bad connection to see how the app behaves
+- If you change something related to the handling of user or application data (model layer) make sure to test the migration of data from a [previous release version of the app](https://github.com/insidegui/WWDC/releases) to your modified version.
+- If you change a component related to networking, use Apple's Network Link Conditioner and test with a slow/bad connection to see how the app behaves. This conditioner is available from [`developer.apple.com`](https://developer.apple.com/download/more/), in the "Additional Tools for Xcode" bundle. 
 - If you change something related to UI, try resizing the window and looking at different content to make sure it can adapt well to different environments.
 
-
 Make sure your code is not introducing any new warnings, including those produced by Swiftlint.
 
-####VII. Dependencies
+#### VII. Dependencies
 
-Do not add dependencies to the project.
+Do not add dependencies to the project. In an ideal world, we would be masters of our own destiny.
 
 Do not bring in assets (icons, images) for which you don't have an appropriate license. Icons and images must have a Creative Commons or similar license to be used in this project. A good place to find free icons is [Icon Finder](https://iconfinder.com).
 
-##3. Conclusion
+## 3. Conduct
+
+The project has a [code of conduct](./CODE_OF_CONDUCT.md) that should be kept in mind when contributing -- whether that contribution is in the form of issues, comments, documentation or code. We reckon the fact that we've never had to enforce this is a pretty good sign of a healthy community, so let's keep it that way. 😉
+
+Try to keep documentation and messages free of phrases that assume knowledge. If you're resorting to phrases like "obviously", "everyone knows" and "just", there's probably some context you're excluding. Not only does this help us be friendlier and more approachable for newcomers (bear in mind the app itself is an educational resource!), but it will probably help any programmer -- even you! -- who comes back to look at your code in months/years.
+
+## 4. Conclusion
 
 These are just some suggestions for common scenarios, if you need help with your contribution you can always open an issue to discuss it before doing the pull request.