Merge pull request #50 from OpenDataServices/october-update

Bunch of October Updates to the developer docs

code-checklist.md

@@ -24,14 +24,20 @@ The creation of this checklist allows us to:
 Each code repository in our [GitHub account](https://github.com/opendataservices/) 
 should have a CHECKLIST.rst file
 
+Before you start
+----------------
+
+Generally, our code should be public, as should  our development processes.
+We use GitHub public repositories to help us achieve this.
+
 The checklist
 -------------
 
 ### 1. We should know which code is 'ours'
 
 Generally Open Data Services Code can be found here: https://github.com/opendataservices
 
-There may be rare instances of code that have yet to make it into the
+However, we often do open development for our customers in thier GitHub organisations as well. There may be rare instances of code that have yet to make it into the
 GitHub organisation account, but it is our desire and intention for all
 Open Data Services code to be there.
 
@@ -133,6 +139,10 @@ This could be by:
 
 - email
 
+In part this is to make sure that we can communicate significant changes 
+to the user of our code. A case to consider would be a change to an API 
+that we maintain for example.
+
 ### 14. Users should be able to communicate with us about our code
 
 There should be pathways for
@@ -210,3 +220,5 @@ Wherever possible, we should support browsers without javascript
 See: http://kryogenix.org/code/browser/everyonehasjs.html)
 
 ### 26. All code should be seen/understood by more than one person
+
+At worst this should involve someone extra checking of all pull requests and newly commited code, even if the code if written by the "owner" of that repo.

code.md

@@ -10,7 +10,8 @@ This may be custom code that has been written specifically to perform
 tasks for Open Data Services, or it could be 'off the shelf' code that we need to
 maintain and update in order for it to run smoothly. Some of it will be
 standalone applications, some of it could be customisations to other
-people's projects/code.
+people's projects/code. Increasingly, we often create code for our customers in 
+their own GitHub organisation.
 
 Some code directly powers projects/web applications. Other code may be
 command line tools that, for example, process data locally, or that
@@ -29,9 +30,16 @@ So which code are we talking about?
 Generally Open Data Services Code can be found here:
 https://github.com/opendataservices
 
+We are also responsible for all the code at:
+https://github.com/ThreeSixtyGiving
+https://github.com/TalkAboutLocal
+
+We are heavily involved in most of the code at:
+https://github.com/open-contracting
+
 There may be rare instances of code that have yet to make it into the
-GitHub organisation account, but it is our desire and intention for all
-Open Data Services code to be there.
+relevant GitHub organisation account, but it is our desire and intention 
+for all Open Data Services code to be there.
 
 Code Checklist
 --------------
@@ -79,7 +87,7 @@ External Testing Services
 
 We use the following external services to test our code in various ways:
 
-* [Travis](https://travis-ci.org/) - runs unit tests every time a commit is made
+* [Travis](https://travis-ci.org/) - runs unit tests every time a commit is made (see also: https://travis-ci.org/OpenDataServices )
 * [Coveralls](https://coveralls.io/) - checks the coverage of those unit tests
 * [Requires.io](https://requires.io) (Python specific) - tests to see whether the Python moudles listed in requirements.txt are up to date 
 * [Landscape](https://landscape.io/) (Python specific) - calculates the quality of the code using static analysis, and tracks this over time

deployment.md

@@ -1,3 +1,12 @@
 # Deployment
 
 ## General approach
+
+We do nearly all of our deployment with the salt deployment tool. http://saltstack.com/
+
+The repository at https://github.com/OpenDataServices/opendataservices-deploy provides lots of information for those familiar with salt.
+
+We currently take a middle ground approach for semi automated deployments for our small setup. This has been described as "Pets with strong configuration management", in slide 17 from these [slides from CERN](http://www.slideshare.net/gmccance/cern-data-centre-evolution):
+
+Future application architectures should use Cattle, but pets with strong configuration management are viable and still needed.
+

general-approaches.md

@@ -18,3 +18,7 @@ We hold regular retrospectives to review our work and our use of agile technique
 ## User-centric design
 
 We recognise that all of our software and standards will be used by humans, and therefore we regularly engage in user research to discover the needs of those who will use the software that we're producing. The way in which we use this knowledge will vary depending on the project, but we will often refer back to the user stories that we're attempting to satisfy during development. 
+
+## We also like
+
+README driven development: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

tools-generic.md

@@ -40,3 +40,10 @@ Favicons
 
 http://realfavicongenerator.net/
 Generate the favicon pictures and HTML code that work on all major browsers and platforms
+
+General Programming
+-------------------
+```
+http://hyperpolyglot.org/
+```
+Useful resource for switching between programming languages

tools/git.md

@@ -9,10 +9,14 @@ In general each repository has:
 
 More specific information about the branches in a repository should be in the CONTRIBUTING.md file in each repository. Merges should be performed or overseen by the person listed in CONTRIBUTING.md.
 
+### Issues
 We use #issueno to reference a GitHub issue from a commit (or OpenDataServices/reponame#issueno to reference an issue from another repository). Where a commit relates to one issue we use [#issueno] at the start of the commit messages to make it easier to scan by eye what issues commits relate to. We generally don't use "fixes #issueno" in order to leave closing issues until it's been checked that they're "Done"
 
+
+### Temporary Branches
 In general having temporary commits on temporary branches is better than using git stash. It's harder to lose your work this way, and they can also be pushed to the server. `tmp-some_name` is our current ad hoc naming convention for temporary branches. If you have a temporary commit you can update it using  `git commit --amend -a --date="`date``
 
+### Branches or Forks?
 We tend to work on branches within the repo in the OpenDataServices (or other relevant repository), rather than in personal forks, as this allows us all to take advantage of the same TravisCI setup etc. (Obviously external contributors will generally not have permissions for this, so will use their personal forks instead.).
 
 ## git tips
@@ -25,6 +29,16 @@ we want to collect - e.g. the different ways of identifying a commit
 - tags, branches, HEAD~2, hash, short hash 0 for use with the git diff 
 etc.
 
+### Push to 2 remotes at once 
+
+http://stackoverflow.com/questions/14290113/git-pushing-code-to-two-remotes#answer-14290145
+
+`git remote set-url --add`
+
+### git blame a diff
+
+See https://github.com/dmnd/git-diff-blame and http://stackoverflow.com/questions/5098256/git-blame-prior-commits
+
 ## Flow chart of steps if you mess up git commits
 
 http://justinhileman.info/article/git-pretty/

tools/huboard.md

@@ -0,0 +1,7 @@
+#Huboard
+
+https://huboard.com/
+
+We tend to use huboard as a way to plan our work.
+
+Where we use huboard to manage a repositories issues, we should add a link from the README so that others can find it.

working-off-line.md

@@ -6,6 +6,8 @@
 wget -m --no-parent  -e robots=off "https://github.com/OpenDataServices/developer-docs/issues/"
 ```
 
+NOTE: This will only fetch the first page of issues.
+
 The best way to view these is probably with a local instance of apache, e.g.:
 ```
 cd github.com
@@ -19,11 +21,11 @@ to work off-line with documents, spreadsheets, etc
 
 ## Developing Off-line
 
-GitHub issues can be grabbed (see above).
+**GitHub** issues can be grabbed (see above).
 
-Git generally works well for offline usage. Remember that if you've done a git fetch (or git pull) before going offline, then you can interact with remote branches at origin/branch_name.
+**Git** generally works well for offline usage. Remember that if you've done a git fetch (or git pull) before going offline, then you can interact with remote branches at origin/branch_name.
 
-We use Content Delivery Networks quite often for style and layout (e.g.
+We use **Content Delivery Networks** quite often for style and layout (e.g.
 Bootstrap), sometimes these can be a pain off-line. These are often heavily cached, so it can be better to be completely offline where the cached copy will be used immediately, rather than online on a flakey connection where the browser may hang checking for new versions of these files. Similarly doing a soft reload with Ctrl+L and then enter may keep the cache, whereas Ctrl+R will try to bust it.
 
-Some of our applications rely on data fetched remotely - we should try to avoid this wherever possible, and describe workarounds in the applications README (e.g. faking with /etc/hosts) where this issue remains.
+Some of our applications rely on **data** fetched remotely - we should try to avoid this wherever possible, and describe workarounds in the applications README (e.g. faking with /etc/hosts) where this issue remains.