Merge lp:~bac/juju-quickstart/hacking-brew into lp:juju-quickstart

[Brad Crittenden]

Add homebrew release instructions.

Also fixed bad coding in HACKING.rst. Used the 'restview'
package from PyPI to verify it. Replaced long embedded
URLs with references. Looks very nice if rendered but
not as good if read as plaintext.

https://codereview.appspot.com/106120043/

[Brad Crittenden (bac)]

Reviewers: mp+223601_code.launchpad.net,

Message:
Please take a look.

Description:
Add homebrew release instructions.

Also fixed bad coding in HACKING.rst. Used the 'restview'
package from PyPI to verify it. Replaced long embedded
URLs with references. Looks very nice if rendered but
not as good if read as plaintext.

https://code.launchpad.net/~bac/juju-quickstart/hacking-brew/+merge/223601

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/106120043/

Affected files (+83, -18 lines):
   M HACKING.rst
   A [revision details]

[Francesco Banconi (frankban)]

LGTM with minor changes. Thank you!

https://codereview.appspot.com/106120043/diff/1/HACKING.rst
File HACKING.rst (right):

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode215
HACKING.rst:215: #. Compute the SHA1 checksum for the tgz and insert it
as the JujuQuickstart
Juju Quickstart?

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode221
HACKING.rst:221: download failures are acceptable.)::
are acceptable)

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode252
HACKING.rst:252: rebase the branch and squash commits before pushing.
Could you give a hint about how much time passes between Jenkins tests
pass and the updated formula is merged? Is it merged right after the
tests run?

https://codereview.appspot.com/106120043/

[Brad Crittenden (bac)]

*** Submitted:

Add homebrew release instructions.

Also fixed bad coding in HACKING.rst. Used the 'restview'
package from PyPI to verify it. Replaced long embedded
URLs with references. Looks very nice if rendered but
not as good if read as plaintext.

R=frankban
CC=
https://codereview.appspot.com/106120043

https://codereview.appspot.com/106120043/diff/1/HACKING.rst
File HACKING.rst (right):

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode215
HACKING.rst:215: #. Compute the SHA1 checksum for the tgz and insert it
as the JujuQuickstart
On 2014/06/18 16:17:24, frankban wrote:
> Juju Quickstart?

Actually brew constructs a Ruby class based on the package name, so in
the file it really is JujuQuickstart.

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode221
HACKING.rst:221: download failures are acceptable.)::
On 2014/06/18 16:17:25, frankban wrote:
> are acceptable)

Done.

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode221
HACKING.rst:221: download failures are acceptable.)::
On 2014/06/18 16:17:25, frankban wrote:
> are acceptable)

Done.

https://codereview.appspot.com/106120043/diff/1/HACKING.rst#newcode252
HACKING.rst:252: rebase the branch and squash commits before pushing.
I will. This update was flawless and when Jenkins passed the bot merged
it in. Total time was about two hours.

https://codereview.appspot.com/106120043/

=== modified file 'HACKING.rst'
--- HACKING.rst	2014-06-11 14:51:38 +0000
+++ HACKING.rst	2014-06-18 16:03:57 +0000
@@ -162,17 +162,18 @@
 The procedure is analogous for pre-trusty series releases, just using the
 other packaging branch.
 
-The recipe for creating packages for trusty and beyond is in:
-<https://code.launchpad.net/~juju-gui-charmers/+recipe/juju-quickstart-trunk-daily>.
-
-The pre-trusty recipe is at:
-<https://code.launchpad.net/~juju-gui-charmers/+recipe/juju-quickstart-pre-trusty-daily>.
-
-We currently publish beta releases on the Juju Quickstart Beta PPA: see
-<https://launchpad.net/~juju-gui/+archive/quickstart-beta/+packages>.
+The recipe for creating packages for trusty and beyond is at
+`juju-quickstart-trunk-daily
+<https://code.launchpad.net/~juju-gui-charmers/+recipe/juju-quickstart-trunk-daily>`_.
+
+The pre-trusty recipe is `juju-quickstart-pre-trusty-daily
+<https://code.launchpad.net/~juju-gui-charmers/+recipe/juju-quickstart-pre-trusty-daily>`_.
+
+We currently publish beta releases on the `Juju Quickstart Beta PPA
+<https://launchpad.net/~juju-gui/+archive/quickstart-beta/+packages>`_.
 When a beta release is ready to be published, we move over the packages from
-the Juju Quickstart Beta PPA to the juju stable packages PPA in
-<https://launchpad.net/~juju/+archive/stable>.
+the Juju Quickstart Beta PPA to the `Juju stable PPA
+<https://launchpad.net/~juju/+archive/stable>`_.
 
 Packages depend on `python-jujuclient` and `python-websocket-client` to be
 available. They are available in trusty and later, and they are also stored in
@@ -182,12 +183,74 @@
 Creating PyPI releases
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Juju Quickstart is present on PyPI: see
-<https://pypi.python.org/pypi/juju-quickstart>.
+Juju Quickstart is present on `PyPI
+<https://pypi.python.org/pypi/juju-quickstart>`_.
 It is possible to register and upload a new release on PyPI by just running
 ``make release`` and providing your PyPI credentials.  Note there are no
 series-specific changes required for publishing to PyPI.
 
+Creating a Homebrew release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The brew formula fetches its source from PyPI, so it must be done after the PyPI
+release.
+
+1. Start with a fresh brew::
+
+    $ brew update
+
+#. Go to PyPI (https://pypi.python.org/pypi/juju-quickstart) and download the
+   new tgz file.
+
+#. Verify the md5 checksum matches that on the PyPI site via, e.g. ::
+
+    $ md5 ~/Downloads/juju-quickstart-1.4.0.tar.gz
+
+#. Use brew to edit the juju-quickstart formula::
+
+    $ brew edit juju-quickstart
+
+#. Update the URL to point to the new release tar.gz file.
+
+#. Compute the SHA1 checksum for the tgz and insert it as the JujuQuickstart
+   sha1 value::
+
+    $ shasum ~/Downloads/juju-quickstart-1.4.0.tar.gz
+
+#. Test the new formula by upgrading juju-quickstart (errors about bottle
+   download failures are acceptable.)::
+
+    $ brew upgrade juju-quickstart
+
+#. Run the formula test::
+
+    $ brew test juju-quickstart
+
+#. Perform full QA as above.
+
+After successful QA, follow the procedure outlined in the Homebrew
+`Formula-Cookbook
+<https://github.com/Homebrew/homebrew/wiki/Formula-Cookbook#commit>`_. The
+project is adamant about having one file and one commit per pull request.
+Rebase and squash commits if required.
+
+1. Move to the brew git directory::
+
+    $ cd `brew repository`
+
+#. Create a new branch, add the changed file, and commit::
+
+    $ git checkout -b juju-quickstart-1.4.0
+    $ git add Library/Formula/juju-quickstart.rb
+    $ git commit -a -m "juju-quickstart 1.4.0"
+    $ git push [e-mail]:juju/homebrew.git juju-quickstart-1.4.0
+
+#. Go to https://github.com/juju/homebrew to create a pull request.
+#. Copy the debian/changelog from the lp:juju-quickstart/packaging as the pull
+   request comment.  Keep the name simple, e.g. 'juju-quickstart 1.4.0'.
+#. Watch the pull request and ensure it passes Jenkins.  If changes must be made,
+   rebase the branch and squash commits before pushing.
+
 Updating application and test dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -196,13 +259,13 @@
 includes the latter, so any updates to the application requirements will also
 update the test dependencies and therefore the testing virtual environment.
 Note that, since the source requirements are dynamically generated parsing
-``requirements.pip``, that file must only include PACKAGE==VERSION formatted
+``requirements.pip``, that file must only include ``PACKAGE==VERSION`` formatted
 dependencies, and not other pip specific requirement specifications.
 
 Also ensure, before updating the application dependencies, that those packages
 are available in the main Ubuntu repositories for the series we support (from
-precise to saucy), or in the Juju Quickstart Beta PPA: see
-<https://launchpad.net/~juju-gui/+archive/quickstart-beta/+packages>.
+precise to saucy), or in the `Juju Quickstart Beta PPA
+<https://launchpad.net/~juju-gui/+archive/quickstart-beta/+packages>`_.
 
 Please also keep up to date the possible values for the environments.yaml
 default-series field (see ``quickstart.settings.JUJU_DEFAULT_SERIES``) and the
@@ -224,12 +287,12 @@
 information about what is going on. The GUI builtin server exposes some bundle
 information in two places:
 
-- https://<juju-gui-url>/gui-server-info displays in JSON format the current
+- ``https://<juju-gui-url>/gui-server-info`` displays in JSON format the current
   status of all scheduled/started/completed bundle deployments;
-- /var/log/upstart/guiserver.log is the builtin server log file, which includes
+- ``/var/log/upstart/guiserver.log`` is the builtin server log file, which includes
   logs output from the juju-deployer library.
 
-Moreover, setting `builtin-server-logging=debug` gives more debugging
+Moreover, setting ``builtin-server-logging=debug`` gives more debugging
 information, e.g. it prints to the log the contents of the WebSocket messages
 sent by the client (usually the Juju GUI) and by the Juju API server.
 As mentioned, juju-deployer works on its own sandbox and uses its own API