readme.md 6.05 KB
Newer Older
1
# Heartbeat Cocoa
2

3
<img width="512px" src="Heartbeat/balloon_512x512@2x.png">
4

5
6
The native reference client for Heartbeat for OS X Yosemite.

7
8
9
10
11
12
## Before you start…

Only designers are allowed to contribute to this code base. If you want to contribute to it, realise that you’re a designer. For every line of code you contribute, ask yourself: does this improve the experience of the person using Heartbeat?

If you believe that the experience of the person using Heartbeat is not your concern, please do not contribute to this codebase.

13
## Conventions
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

### Accessibility

Accessibility is not an afterthought or a layer; we consider it continuously at design and development time.

A feature is not complete and won’t be accepted until it is accessible.

We see accessibility as usability for audiences with special needs. These may be environmental, physical, or psychological in nature. They may be temporary or permanent. And they may vary in severity.

We also recognise that the needs of different audiences may be different and may even conflict with one another (e.g., high contrast text may aid people with visual challenges or people viewing the app in bright sunlight but may hinder comprehension for people with dyslexia).

### Localisation and internationalisation

Localisation and internationalisation, like Accessibility (and related to Accessibility) are not an afterthought or a layer; we consider them continuously at design and development time.

A feature is not complete until it is internationalised and localised into the supported languages.

We are initially starting with one localisation (Turkish) as that is the foreign language I’m (Aral) fluent in, in addition to English. Others will follow.

### Views and auto layout constraints

#### Use Interface builder to lay out views

We use Interface Builder to lay out views and tweak constraints. The live preview is especially useful for testing localisation and responsiveness.

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
Please keep the storyboard(s) tidy and lay out your objects so that they are grouped logically.

We take pride in how the app looks on the inside as well as on the outside.

#### Give all views an Identifier

The convention is to name your identifiers so that if you had a custom class for the view, it would have the same name, written with the same capitalisation.

e.g., ```PreloaderView```

This, among other things, helps when debugging constraint-related issues in Auto Layout as it produced nicer Visual Format Language strings.

#### Name all elements in the Document Outline view

Base the visual element name on its identifier/class name but use spaces so that it is easier to read.

e.g., ```Preloader View```

57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
#### Recreate constraints in code

However, we then recreate the constraints in code in the ```viewWillAppear``` method of View Controllers. 

This involves:

1. Removing existing constraints: ```view.removeConstraints(self.view.constraints)```
2. Setting up the constraints using [Cartography](https://github.com/robb/Cartography).

At the cost of some repitition (of tasks, not code), we get the benefit of knowing *exactly* which constraints are affecting our views (and the ability to quickly alter them all from one place) while also maintaining the rapid prototyping and experimentation that Interface Builder affords us.

For more discussion on this, see the Labs post on [Animating Cocoa Window Size When Using Auto Layout](https://ind.ie/labs/blog/animating-cocoa-window-size-when-using-auto-layout/)

### Code consistency

We use:

1. Tabs not spaces
2. Curly brackets on their own line
3. White space and comments liberally to aid intent and comprehension. e.g., 
	
        //
        // Scale the Heartbeat balloon to full size. 
        // (This is our launch-time progress indicator.)
        //
		layout (balloonImageView)
        {
            /* as */ balloonImageView in
            
            balloonImageView.left == balloonImageView.superview!.left
            balloonImageView.right == balloonImageView.superview!.right
            balloonImageView.top == balloonImageView.superview!.top
            balloonImageView.bottom == balloonImageView.superview!.bottom
        }

We code for intent and consistency and we do not prematurely optimise.

When in doubt, stick to the formatting you see elsewhere in the source. If you see a discrepancy, please flag it.

Aral Balkan's avatar
Aral Balkan committed
96
**Remember these wise words by Brian Kernighan and P. J. Plauger:**
97
98
99

*‘Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.’*

Adam Procter's avatar
Adam Procter committed
100
101
102
103
104
105
## Basic Install

Once you have cloned the repository you need to run the ./install and ./dev commands before you can build the Heartbeat XCode project. You may also need to install coffee-script. This is all done via terminal.

Then run the standard install as follows;

Adam Procter's avatar
Adam Procter committed
106
107
	./install
	./dev
Adam Procter's avatar
Adam Procter committed
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

If you come across the error when running ./install;
	
	line 13: coffee: command not found

You will need to install coffee-script as follows;

	sudo npm -g install coffee-script

Please note before you build in XCode, if you are part of the ind.ie alpha team and building on the same Mac you should make sure you back up your container found at 

	~/Library/Containers/ind.ie.Heartbeat 

Please back up this folder before testing so you can have one sandbox for local testing and one for your main account. You don't want to corrupt your ind.ie alpha account.

123
124
125
126
## Common issues and troubleshooting

### App crashes after repeatedly getting errors that Pulse has crashed.

127
#### Reason
128
129
130

Dangling Pulse process.

131
#### Workaround
132

133
134
135
136
137
138
139
140
141
Run the ```killnode``` script and restart Heartbeat.

## Credits &amp; license

Made with ❤ at [Ind.ie][4]

Copyright &copy; 2014-2015 [Aral Balkan][2], Ind.ie. All Rights Reserved.

We are working on a license that is free as in freedom and yet allows us to publish and distribute Heartbeat on the App Store. In the meanwhile, we are releasing the code, all rights reserved, for review. To follow the updates, please see the [Towards Ind.ie Commons Licenses](https://forum.ind.ie/t/towards-ind-ie-commons-licenses/690) thread on the Ind.ie forum.