Merge lp:~julian-edwards/gwacl/hacking into lp:gwacl

[Julian Edwards]

Add HACKING.txt and clean up README.

[lp:~julian-edwards/gwacl/hacking]

124. By Julian Edwards on 2013-06-21

another cleanup

[Gavin Panella (allenap)]

Looks good!

[1]

+All branch submissions must be formatted using "make format".  They must
+also have a successful test run with "make check".  New features must
+always be accompanied by new tests.

You could use ``blah`` to get monospace here:

  All branch submissions must be formatted using ``make format``.  They must
  also have a successful test run with ``make check``.  New features must
  always be accompanied by new tests.

[2]

+You also need to install go-curl::
+
+   go get github.com/andelf/go-curl

Doesn't this get getted when getting gwacl? I know this is just a move
of what's already there, but it might be worth dropping now if it
really is superfluous.

[3]

+When adding new API entry points to the library, we have decided that all
+of these should take a single struct parameter, which itself contains one
+or more parameters.

The "we have decided" bit doesn't sound good. How about just stating
how it should be done:

  API functions should take a single struct parameter, which itself
  contains one or more parameters. Existing functions that do not
  follow this rule are historic and should not be copied.

review: Approve

[lp:~julian-edwards/gwacl/hacking]

125. By Julian Edwards on 2013-06-24

review comments

=== added file 'HACKING.txt'
--- HACKING.txt	1970-01-01 00:00:00 +0000
+++ HACKING.txt	2013-06-24 00:41:26 +0000
@@ -0,0 +1,62 @@
+==================================================
+Hacking in GWACL (Go Windows Azure Client Library)
+==================================================
+
+(this doc is a huge WIP)
+
+Submitting changes
+------------------
+
+`GWACL`_ is hosted on Launchpad using `Bazaar`_.  Submitting a change
+requires you to create a merge proposal against the trunk branch and a
+core committer will then review the branch.  Once the branch is accepted,
+it will be landed by the reviewer.
+
+All branch submissions must be formatted using ``make format``.  They must
+also have a successful test run with ``make check``.  New features must
+always be accompanied by new tests.
+
+.. _GWACL: https://launchpad.net/gwacl
+.. _Bazaar: http://bazaar.canonical.com/
+
+
+Prerequisites
+-------------
+
+The code that communicates with Azure's management API uses *libcurl*, through
+a Go language binding called *go-curl*.  You need to install the libcurl
+headers for your OS.  On Ubuntu this is::
+
+   sudo apt-get install libcurl4-openssl-dev
+
+If you didn't ``go get`` gwacl you may also need to install go-curl::
+
+   go get github.com/andelf/go-curl
+
+On Ubuntu 12.10 at least, you specifically need the given version of libcurl.
+With other versions you will receive unexpected "403" HTTP status codes
+("Forbidden") from the Azure server.
+
+Why use libcurl?  At the time of writing, Go's built-in http package does not
+support TLS renegotiation.  We find that Azure forces such a renegotiation
+when we access the management API.  The use of libcurl is embedded so that
+future implementations can swap it out for a different http library without
+breaking compatibility.
+
+
+API philosophy
+--------------
+
+API functions in the library should take a single struct parameter, which
+itself contains one or more parameters.  Existing functions that do not follow
+this rule are historic and should not be copied.
+
+This brings several advantages::
+
+    1. Keyword parameters improve callsite readability.
+    2. It allows for parameters to be defaulted if not supplied.
+    3. It's much easier to change the API later without breaking existing
+       code, it just needs re-compiling in the case where you add new,
+       optional, parameters.
+
+

=== modified file 'README'
--- README	2013-06-17 14:14:07 +0000
+++ README	2013-06-24 00:41:26 +0000
@@ -3,29 +3,7 @@
 ===========================================
 
 
-Random notes, clean this up later
-=================================
-
-
-Install libcurl
----------------
-
-The code that communicates with Azure's management API uses *libcurl*, through
-a Go language binding called *go-curl*.  Install the libcurl headers and
-go-curl::
-
-   sudo apt-get install libcurl4-openssl-dev
-   go get github.com/andelf/go-curl
-
-On Ubuntu 12.10 at least, you specifically need the given version of libcurl.
-With other versions you will receive unexpected "403" HTTP status codes
-("Forbidden") from the Azure server.
-
-Why use libcurl?  At the time of writing, Go's built-in http package does not
-support TLS renegotiation.  We find that Azure forces such a renegotiation
-when we access the management API.  The use of libcurl is embedded so that
-future implementations can swap it out for a different http library without
-breaking compatibility.
+(Work In Progress)
 
 
 Generate an x509 key to talk to Azure