Update and expand contributing section of Readme

[vkz]

Imho, Contributing section of the README ought to be updated and expanded. Its current bare state doesn't reflect the process a potentially inexperienced contributor may need to go through to get the project off the ground. Perhaps start with a clean slate:

• no rbenv, no carthage, no xcode, only homebrew,
• assume fair programmer, not a complete newbie, but perhaps not versed with Apple's ecosystem,
• fix what's clearly broken due to, say, newer version of Swift, Xcode or whatever,
• document remaining gotchas.

He's a handful of issues I ran into while following the above steps:

• 570

• one needs to open Amethyst.xcworkspace not the xcodeproj - obvious to everyone but the every programmer in the world, who never programmed for Apples ecosystem

• swiftlint reports >47 issues and fails the build, looks like swiftlint autocorrect doesn't work with the latest version of XCode

  • lets run swiftlint autocorrect on command line. Fails to fix most issues.
  • lets just give up and remove offending lint from the build phases. Why lint at all then?
  • ok, we end up with just one last issue

    Module compiled with swift 3.0.2 cannot be imported in Swift 3.1

  turns out carthage pulled pre-compiled binaries. Why pull binaries at all? Why not compile with whatever Swift version is available locally? Lets fix it with carthage update --platform osx --no-use-binaries.

None of those weird words were familiar to me when I first tried to build Amethyst. Google helps a ton but the gap between cloning a repo and building it is so huge that only the hardcore or very experienced contributors would persist. Reason I write about these problems here instead of submitting a PR for the README is because they are arguably easier to fix than document.

Trello Card

[ianyh]

Added some improvements and a better setup script that tries to walk you through the process to make sure everything gets set up. Also updated code for Xcode/swift/swiftlint upgrades. It still makes some assumptions about having homebrew and Xcode installed.

A couple notes:

• A substantial piece of the confusion here likely came from new versions of software resulting in changes in behavior.
• swiftlint autocorrect is working correctly, but it doesn't fix everything. A lot of the errors produced were because of capitalization of enumerations, for example, and those can't be automatically updated without breaking code that references the enumeration.
• Allowing downloaded binaries instead of building is just a performance optimization. This is mostly to improve performance of running tests.

I'll try to address more of this when I can. Apologies for the confusing process.

[vkz]

Script works beautifully. Thank you very much!

May I also suggest just a small note in Contributing section as regards to Signing. This is simply to help the unprepared like myself. When you first open Amethyst.xcworkspace chances are General - Signing tab in XCode will have your Team chosen by default. Build will consequently fail since person running it isn't part of that team. Sadly, I forget the exact error and can't get my xcode back in that state. Solution is to Team - Add Account and log in with your Apple credentials and then build with those. Please, correct any mistakes in my description - I am a total noob with Apples ecosystem.

[vkz]

Related and perhaps better for those who do not have Apple Developer ID, maybe have a small paragraph about exporting an app with introduced fixes, so that people could enjoy fruits of their labor without waiting for their changes merged upstream and a new build distributed. Such section could read something like this:

Let's assume you do not have an Apple Developer ID but still want to install Amethyst with your changes locally without the need to Run it from XCode every time. You'll need to forgo code-signing entirely, build and export Amethyst unsigned:

1. Select Amethyst workspace
2. General - Signing: choose None
3. Build Settings - Code Signing Identity: choose Don't Code Sign
4. From menu Product choose Archive. This will build Amethyst and open a popup window where you need to choose your latest build, then click Export button on the right.

Once exported, you should be able to navigate to your exported Amethyst.app and launch it as usual. Don't forget to allow it to control your computer in: System Preferences - Security & Privacy - Accessibility.

item 3. above comes courtesy of this SO answer

[ianyh]

I'm just going to disable code signing. It's only relevant to me right now, and unnecessary for development. See #579

[ianyh]

I think most of this is accomplished with the new setup script. It tells you what you don't have installed.