yellow team mailing list archive

[Nicola Larosa <nicola.larosa@xxxxxxxxxxxxx>]

Nicola Larosa has proposed merging lp:~teknico/juju-gui/1086512-revise-docs into lp:juju-gui.

Requested reviews:
  Juju GUI Hackers (juju-gui)
Related bugs:
  Bug #1086512 in juju-gui: "README.txt should contain deployment information"
  https://bugs.launchpad.net/juju-gui/+bug/1086512

For more details, see:
https://code.launchpad.net/~teknico/juju-gui/1086512-revise-docs/+merge/139226

Put deploy docs in README, add HACKING.

Move the development instructions from the README file to a newly created HACKING one, update them, link the HACKING into the docs. Put deploying instructions in the README file. Revise all docs updating them, and fixing markup and links.

https://codereview.appspot.com/6924047/

-- 
https://code.launchpad.net/~teknico/juju-gui/1086512-revise-docs/+merge/139226
Your team Juju GUI Hackers is requested to review the proposed merge of lp:~teknico/juju-gui/1086512-revise-docs into lp:juju-gui.

=== added file 'HACKING'
--- HACKING	1970-01-01 00:00:00 +0000
+++ HACKING	2012-12-11 15:16:34 +0000
@@ -0,0 +1,197 @@
+===========
+Development
+===========
+
+Here is how to develop on this codebase.
+
+Developer Install
+=================
+
+Juju GUI uses nodejs based development tools.
+
+You'll need nodejs & npm from the ppa::
+
+  $ sudo add-apt-repository ppa:chris-lea/node.js
+  $ sudo apt-get update
+  $ sudo apt-get install nodejs npm
+
+You also need ImageMagick::
+
+  $ sudo apt-get install imagemagick
+
+The linter will be installed locally per branch, but if you want editor
+integration, you may want to install jshint globally in your system::
+
+  $ sudo npm install -g jshint
+
+For building the docs, you also need sphinx::
+
+  $ sudo apt-get install python-sphinx
+
+To make releases, you'll need pytz::
+
+  $ sudo apt-get install python-tz
+
+The gui frontend can be installed with::
+
+  $ bzr branch lp:juju-ui trunk
+  $ cd trunk
+  $ make server
+
+It may take a while for the server to start the first time as npm will
+need to download packages.  When ready, the server will print:
+
+Server listening on 8888
+
+You can then access the GUI at <http://localhost:8888/>.
+
+You'll also need to deploy a juju environment with REST api access.
+Currently that work resides in a pipeline of juju branches. The
+recommended branch to use as a server is ``lp:~hazmat/juju/rapi-rollup``.
+
+You can use it with any environment, but for dev purposes, a local
+environment works well. One environment option specific to this branch
+is the api-port. An appropriate sample configuration::
+
+  default: dev
+  environments:
+    dev:
+      type: local
+      data-dir: /home/kapil/.juju/local
+      admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4
+      default-series: precise
+      juju-origin: ppa
+      api-port: 8081
+
+Note that juju-origin is set to the ppa, the api server runs outside of
+the container, and is launched using whichever branch you're using.
+
+Also note that the api-port should be set at 8081, which the gui's
+initial environment connection currently defaults to.
+
+You'll need to bootstrap the local environment, and deploy one service.
+The api server needs access to the provisioning credentials which are
+lazily initialized in juju upon usage.
+
+Juju-gui and rapi-rollup can communicate via an encrypted WebSockets
+connection: to enable it, add the following line to the config above::
+
+  api-secure: true
+
+You will also need to edit your ``app/config.js`` replacing
+``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.
+
+By default, rapi-rollup uses a self-signed certificate; because of that you
+will need to visit the <https://localhost:8081/ws> WebSockets URL with your
+browser and accept the included self-signed certificate, or the WebSockets
+encrypted connection will not work.
+
+In order to use a different certificate, you add an api-keys option to the
+config above: its value will be the path of the directory containing the
+certificate and the private key, whose filenames will have to be respectively
+``juju.crt`` and ``juju.key``.
+
+After which, the gui should be functional (it automatically polls the
+api server for establishing a websocket).
+
+Running unit tests
+==================
+
+  $ make test
+
+Running lint
+============
+
+  $ make lint
+
+API documentation
+=================
+
+Generated JavaScript documentation is available in the yuidoc directory after
+running the command ``make yuidoc``. You can view the docs by running::
+
+  $ xdg-open yuidoc/index.html
+
+The `documentation <http://yui.github.com/yuidoc/syntax/>`_ for YUIDoc markup
+is available.
+
+Project documentation
+=====================
+
+The project documentation is available in the ``docs/`` directory. It needs
+Sphinx::
+
+  $ sudo apt-get install python-sphinx
+
+Build the documentation::
+
+  $ make doc
+
+(This will also generate the above mentioned yuidoc documentation.)
+
+View it::
+
+  $ xdg-open docs/_build/html/index.html
+
+Making releases
+===============
+
+To make a release, you must either be in a checkout of lp:juju-gui
+without uncommitted changes, or you must override one of the
+`pertinent variable names`_ to force a release.
+
+.. _`pertinent variable names`: `Potentially Useful Release-Oriented Makefile Variables`_
+
+You also need to have a gpg key, and the python-pytz package installed (as
+well as launchpadlib, but that is installed by default in Ubuntu).
+
+See the Process document (docs/process.rst) for step-by-step checklists to
+make developer and stable releases.
+
+Potentially Useful Release-Oriented Makefile Variables
+------------------------------------------------------
+
+The following is a list of pertinent Makefile variables.
+
+FINAL
+  Set FINAL to any non-empty value to make a final release. This will cause
+  the bzr revno to be omitted from the tarball name, and (if you use the
+  release target) will cause the release to be uploaded to the stable series
+  rather than the trunk series. Example usage::
+
+    $ FINAL=1 make release
+
+PROD
+  By default, releases will be uploaded to staging.launchpad.net, which is a
+  separate version of Launchpad that uses a temporary database.  This can be
+  convenient for trying out the release process in the Makefile without
+  affecting our actual production releases.  Set PROD to any non-empty value
+  to send uploads to launchpad.net, the production version of Launchpad, when
+  you are ready to make a real release.
+
+  Note that you may need to ask the webops to turn off the two-factor
+  authentication on your Launchpad staging account in order for the staging to
+  work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
+  something like "webops, could you disable 2FA on my staging account?"
+
+  Example usage::
+
+    $ PROD=1 make release
+
+IS_TRUNK_CHECKOUT
+  Set this to any non-empty value to force the Makefile to believe it is
+  working with a trunk checkout. Example usage::
+
+    $ IS_TRUNK_CHECKOUT=1 make release
+
+HAS_NO_CHANGES
+  Set this to any non-empty value to force the Makefile to believe that the
+  current code tree has no changes. Example usage::
+
+    $ HAS_NO_CHANGES=1 make release
+
+IS_SAFE_RELEASE
+  Set this to any non-empty value to force the Makefile to bypass checks of
+  IS_TRUNK_CHECKOUT and HAS_NO_CHANGES. Example usage::
+
+    $ IS_SAFE_RELEASE=1 make release

=== modified file 'README'
--- README	2012-12-10 14:20:35 +0000
+++ README	2012-12-11 15:16:34 +0000
@@ -1,197 +1,37 @@
-======
-README
-======
-
-Developer Install
-=================
-
-Juju GUI uses nodejs based development tools.
-
-You'll need nodejs & npm from the ppa::
-
-  $ sudo add-apt-repository ppa:chris-lea/node.js
-  $ sudo apt-get update
-  $ sudo apt-get install nodejs npm
-
-You also need ImageMagick::
-
-  $ sudo apt-get install imagemagick
-
-The linter will be installed locally per branch, but if you want editor
-integration, you may want to install jshint globally in your system::
-
-  $ sudo npm install -g jshint
-
-For building the docs, you also need sphinx::
-
-  $ sudo apt-get install python-sphinx
-
-To make releases, you'll need pytz::
-
-  $ sudo apt-get install python-tz
-
-The gui frontend can be installed with::
-
-  $ bzr branch lp:juju-ui trunk
-  $ cd trunk
-  $ make server
-
-It may take a while for the server to start the first time as npm will
-need to download packages.  When ready, the server will print:
-
-Server listening on 8888
-
-You can then access the GUI at http://localhost:8888
-
-You'll also need to deploy a juju environment with REST api access.
-Currently that work resides in a pipeline of juju branches. The
-recommended branch to use as a server is ``lp:~hazmat/juju/rapi-delta``.
-
-You can use it with any environment, but for dev purposes, a local
-environment works well. One environment option specific to this branch
-is the api-port. An appropriate sample configuration::
-
-  default: dev
-  environments:
-    dev:
-      type: local
-      data-dir: /home/kapil/.juju/local
-      admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4
-      default-series: precise
-      juju-origin: ppa
-      api-port: 8081
-
-Note that juju-origin is set to the ppa, the api server runs outside of
-the container, and is launched using whichever branch you're using.
-
-Also note that the api-port should be set at 8081, which the gui's
-initial environment connection currently defaults to.
-
-You'll need to bootstrap the local environment, and deploy one service.
-The api server needs access to the provisioning credentials which are
-lazily initialized in juju upon usage.
-
-Juju-gui and rapi-delta can communicate via an encrypted WebSockets
-connection: to enable it, add the following line to the config above::
-
-  api-secure: true
-
-You will also need to edit your ``app/config.js`` replacing
-``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.
-
-By default, rapi-delta uses a self-signed certificate; because of that you
-will need to visit the https://localhost:8081/ws WebSockets URL with your
-browser and accept the included self-signed certificate, or the WebSockets
-encrypted connection will not work.
-
-In order to use a different certificate, you add an api-keys option to the
-config above: its value will be the path of the directory containing the
-certificate and the private key, whose filenames will have to be respectively
-``juju.crt`` and ``juju.key``.
-
-After which, the gui should be functional (it automatically polls the
-api server for establishing a websocket).
-
-Running unit tests
-==================
-
-  $ xdg-open test/index.html
-
-Documentation
-=============
-
-Generated JavaScript documentation is available in the yuidoc directory.
-Start with the index.html file. You can view the docs by running::
-
-  $ xdg-open yuidoc/index.html
-
-To regenerate the docs run::
-
-  $ make yuidoc
-
-The documentation for YUIDoc markup is at
-http://yui.github.com/yuidoc/syntax/ .
-
-Running lint
-============
-
-  $ jshint --config=jshint.config `bzr ls -RV -k file | grep -v assets/`
-
-Making releases
-===============
-
-To make a release, you must either be in a checkout of lp:juju-gui
-without uncommitted changes, or you must override one of the
-`pertinent variable names`_ to force a release.
-
-.. _`pertinent variable names`: `Potentially Useful Release-Oriented Makefile Variables`_
-
-You also need to have a gpg key, and the python-pytz package installed (as
-well as launchpadlib, but that is installed by default in Ubuntu).
-
-See the Process document (docs/process.rst) for step-by-step checklists to
-make developer and stable releases.
-
-Potentially Useful Release-Oriented Makefile Variables
-------------------------------------------------------
-
-The following is a list of pertinent Makefile variables.
-
-FINAL
-  Set FINAL to any non-empty value to make a final release. This will cause
-  the bzr revno to be omitted from the tarball name, and (if you use the
-  release target) will cause the release to be uploaded to the stable series
-  rather than the trunk series. Example usage::
-
-    $ FINAL=1 make release
-
-PROD
-  By default, releases will be uploaded to staging.launchpad.net, which is a
-  separate version of Launchpad that uses a temporary database.  This can be
-  convenient for trying out the release process in the Makefile without
-  affecting our actual production releases.  Set PROD to any non-empty value
-  to send uploads to launchpad.net, the production version of Launchpad, when
-  you are ready to make a real release.
-
-  Note that you may need to ask the webops to turn off the two-factor
-  authentication on your Launchpad staging account in order for the staging to
-  work. Go to the #launchpad-ops channel on the Canonical IRC server and ask
-  something like "webops, could you disable 2FA on my staging account?"
-
-  Example usage::
-
-    $ PROD=1 make release
-
-IS_TRUNK_CHECKOUT
-  Set this to any non-empty value to force the Makefile to believe it is
-  working with a trunk checkout. Example usage::
-
-    $ IS_TRUNK_CHECKOUT=1 make release
-
-HAS_NO_CHANGES
-  Set this to any non-empty value to force the Makefile to believe that the
-  current code tree has no changes. Example usage::
-
-    $ HAS_NO_CHANGES=1 make release
-
-IS_SAFE_RELEASE
-  Set this to any non-empty value to force the Makefile to bypass checks of
-  IS_TRUNK_CHECKOUT and HAS_NO_CHANGES. Example usage::
-
-    $ IS_SAFE_RELEASE=1 make release
-
-More documentation
-==================
-
-Install Sphinx::
-
-  $ sudo apt-get install python-sphinx
-
-Build the docs::
-
-  $ cd docs
-  $ make html
-
-View them::
-
-  $ xdg-open _build/html/index.html
+========
+Juju-GUI
+========
+
+Welcome. Juju-GUI is a web-based GUI for `Juju <https://juju.ubuntu.com/>`_.
+Juju lets you deploy connected services to the cloud in a convenient,
+vendor-neutral, and powerful way. The GUI lets you visualize and manage
+your work more intuitively from a web browser.
+
+See also:
+
+- `The new Juju GUI: because a picture paints a thousand words
+  <http://blog.canonical.com/2012/10/29/the-new-juju-gui-because-a-picture-paints-a-thousand-words/>`_
+- a `demo of trunk <http://uistage.jujucharms.com:8080/>`_, which is reset
+  every 15 minutes.
+
+Deploy
+======
+
+There are no official releases of Juju-GUI yet, so you have to get the source
+code from Launchpad::
+
+  $ bzr branch lp:juju-gui
+
+The most useful available commands are shown by the command::
+
+  $ make help
+
+You'll typically want to run one of ``make prod``,  ``make debug`` or ``make
+devel`` to deploy an environment. You might also run ``make test`` to check
+that everything is ok. You may also run ``make doc`` to generate the available
+documentation.
+
+Configure
+=========
+
+TBD

=== modified file 'docs/architecture.rst'
--- docs/architecture.rst	2012-10-05 09:42:27 +0000
+++ docs/architecture.rst	2012-12-11 15:16:34 +0000
@@ -6,55 +6,54 @@
 ========
 
 MVC YUI
-~~~~~~~
+-------
 
-Juju-gui is based on yui's backbone style app framework. The official docs
-for this are highly recommended for developers:
-http://yuilibrary.com/yui/docs/app/
+Juju-gui is based on yui's backbone style app framework. The `official docs
+<http://yuilibrary.com/yui/docs/app/>`_ are highly recommended for developers.
 
 An overview of the individual pieces.
 
-- Router - Route dispatch by url, saves and restores url state.
-  http://yuilibrary.com/yui/docs/router/
-
-- Views - Rendering of a view
-  http://yuilibrary.com/yui/docs/view/index.html
-
-- Model - Domain objects with change events
-  http://yuilibrary.com/yui/docs/model/
-  http://yuilibrary.com/yui/docs/model-list/
+- `Router <http://yuilibrary.com/yui/docs/router/>`_ - Route dispatch by url,
+  saves and restores url state.
+
+- `Views <http://yuilibrary.com/yui/docs/view/index.html>`_ - Rendering of a
+  view.
+
+- `Model <http://yuilibrary.com/yui/docs/model/>`_,
+  `ModelList <http://yuilibrary.com/yui/docs/model-list/>`_ - Domain objects
+  with change events.
 
 Environment Integration
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 The gui connects and communicates to the environment over a web socket
 connection.
 
 RPC Calls
-~~~~~~~~~
+---------
 
 Completion callbacks can be used with any of the methods on the environment.
 Multiple calls are done in parallel.
 
 RPC Events
-~~~~~~~~~~
+----------
 
 Messages from the backend for known rpc operation results are messaged out as
 Environment events.
 
 Delta Stream
-~~~~~~~~~~~~
+------------
 
 A stream of object changes, used to update models.
 
 Scenarios
----------
+~~~~~~~~~
 
 - new client
 - existing client disconnects and reconnects
 
 Requirements
-------------
+~~~~~~~~~~~~
 
 ::
 
@@ -67,14 +66,14 @@
   -- delta
 
 Questions
-~~~~~~~~~
-
-Model Composition and relations.
-
-relations by id
-
-We have multiple object states for a given.
-
-Inline combo handler for yui: https://github.com/rgrove/combohandler
-
-More complicated but similiar: https://github.com/jafl/YUI-3-Stockpile
+---------
+
+- Model Composition and relations.
+
+- relations by id
+
+- We have multiple object states for a given.
+
+- Inline combo handler for YUI: <https://github.com/rgrove/combohandler>.
+
+- More complicated but similiar: <https://github.com/jafl/YUI-3-Stockpile>.

=== modified file 'docs/d3-component-framework.rst'
--- docs/d3-component-framework.rst	2012-11-29 03:54:35 +0000
+++ docs/d3-component-framework.rst	2012-12-11 15:16:34 +0000
@@ -1,5 +1,5 @@
 ======================
-D3 Component Framework
+D3 component framework
 ======================
 
 The D3 Component codebase is a small framework with the following goals:
@@ -15,14 +15,14 @@
 explain this usage as it exists today.
 
 The framework only models two high level objects, Component and Module. A
-Component is a top level container around Module objects. The Component 
+Component is a top level container around Module objects. The Component
 provides the implementation of the declarative behavior provided by the
 framework. The Module(s) implement the logical sections of the application. In
 the YUI world it might be common to expect each Module to be the application's
 rendering and interactive behavior around a single YUI App.Model or
 App.ModelList.
 
-Module Writers Guide
+Module writers guide
 ====================
 
 Using the component framework means taking advantage of the tools offered
@@ -76,14 +76,14 @@
 this point that any d3js synthetic events are bound to the canvas (see the
 section on events below). This separation of phases exists to make the life of
 the Module writer simpler. They can rely on whatever elements they'll be drawing
- (adding children to an svg object for example) will already have its container 
- properly available due to the renderOnce setup. They can also be sure that 
- any ``update`` driven intermediate data will be computed and available for
- use in ``render``. This reduces the need for checks in each module to assert
- the most basic DOM state.
+(adding children to an svg object for example) will already have its container
+properly available due to the renderOnce setup. They can also be sure that
+any ``update`` driven intermediate data will be computed and available for
+use in ``render``. This reduces the need for checks in each module to assert
+the most basic DOM state.
 
-After the initial render its expected that updates to the scene occur via the 
-event handlers in the various modules. Render will not usually need to be called 
+After the initial render its expected that updates to the scene occur via the
+event handlers in the various modules. Render will not usually need to be called
 more than once unless the entire Component rendering is removed from the DOM and
 then later re-attached.
 
@@ -228,7 +228,7 @@
 ``this`` for handlers. Phase can be ``before``, ``on``, or ``after``, with ``on`` being
 the default.
 
-Complete Example
+Complete example
 ================
 
 Here is a complete example of a module, with some description. The tests for

=== added symlink 'docs/hacking.rst'
=== target is u'../HACKING'
=== modified file 'docs/index.rst'
--- docs/index.rst	2012-11-28 12:30:32 +0000
+++ docs/index.rst	2012-12-11 15:16:34 +0000
@@ -13,6 +13,7 @@
    :maxdepth: 2
 
    readme
+   hacking
    style-guide
    architecture
    d3-component-framework

=== modified file 'docs/process.rst'
--- docs/process.rst	2012-12-10 14:20:35 +0000
+++ docs/process.rst	2012-12-11 15:16:34 +0000
@@ -1,14 +1,14 @@
 =============
-Process Notes
+Process notes
 =============
 
-Checklist for Starting a Branch
+Checklist for starting a branch
 ===============================
 
 - Understand the problem.  If you don't, ask and be persistent until you do.
-- When determining a solution, consider this preferred Software
-  Architecture Cheat Sheet:
-  http://gorban.org/post/32873465932/software-architecture-cheat-sheet
+- When determining a solution, consider this preferred `Software
+  Architecture Cheat Sheet
+  <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_
 - Have a pre-implementation call with someone about your solution.  If you
   are not sure of your solution, prototype before the pre-implementation call.
 - Use TDD.  Your prototype might be perfect, but you can still move it aside
@@ -16,9 +16,9 @@
 - Update the CHANGES.yaml file with your changes.  The newest (topmost)
   section should have the version "unreleased".  If not and you are
   making changes, add an "unreleased" section at the top.  All other
-  version numbers follow Semantic Versioning (http://semver.org/).
+  version numbers follow `Semantic Versioning <http://semver.org/>`_.
 
-Checklist for Preparing for a Review
+Checklist for preparing for a review
 ====================================
 
 - Round-trips with reviewers are expensive. Try to eliminate them.
@@ -60,7 +60,7 @@
 Once you have two approving reviews (and no disapproving reviews), you may
 land your branch.
 
-Checklist for Reviewing
+Checklist for reviewing
 =======================
 
 - Run ``make test`` and confirm that tests pass.
@@ -79,8 +79,8 @@
   * Make sure that new code has tests.
   * Make sure you can understand the new code.  Ask for clarification if
     necessary.
-  * Consider the advice in this preferred Software Architecture Cheat Sheet.
-    http://gorban.org/post/32873465932/software-architecture-cheat-sheet
+  * Consider the advice in this preferred `Software Architecture Cheat Sheet
+    <http://gorban.org/post/32873465932/software-architecture-cheat-sheet>`_
   * Make sure changes to a file correspond to the naming conventions and other
     stylistic considerations local to that file, and within our project.
   * Before you ask for a change, think and make sure you can't compromise
@@ -92,7 +92,7 @@
   want to re-review after the changes, or if you automatically approve if the
   changes are made.
 
-Checklist for Making a Stable Release
+Checklist for making a stable release
 =====================================
 
 - Get a checkout of the trunk:: ``bzr co lp:juju-gui``.
@@ -145,7 +145,7 @@
 
 You are done!
 
-Checklist for Making a Developer Release
+Checklist for making a developer release
 ========================================
 
 - Get a checkout of the trunk:: ``bzr co lp:juju-gui``.
@@ -202,7 +202,7 @@
 
 You are done!
 
-Checklist for Running a Daily Meeting
+Checklist for running a daily meeting
 =====================================
 
 Move quickly if possible. :-)
@@ -243,7 +243,7 @@
     of reduced availability, request help such as code reviews or pair requests,
     etc.
 
-Checklist for Running a Weekly Retrospective
+Checklist for running a weekly retrospective
 ============================================
 
 Do not go over allotted time.  Try to move quickly to discuss all
@@ -300,7 +300,7 @@
   - Experiment?
   - Another process change?
 
-Slack Project Policy
+Slack project policy
 ====================
 
 - The project should further Canonical in some aspect.  Examples include

=== modified file 'docs/style-guide.rst'
--- docs/style-guide.rst	2012-11-07 18:41:11 +0000
+++ docs/style-guide.rst	2012-12-11 15:16:34 +0000
@@ -1,5 +1,5 @@
 ===========
-Style Guide
+Style guide
 ===========
 
 This guide is an attempt to describe a code style that both works well with the
@@ -160,13 +160,13 @@
 ========
 
 We use YUIDoc to document the applications internals.  YUIDoc comments
-start with "/**" and end with "*/".  The Makefile includes a simple
+start with ``/**`` and end with ``*/``.  The Makefile includes a simple
 linter that enforces YUIDoc comments for each function in the
 application.
 
 This simple linting sometimes means that functions that we might not
 otherwise document require documentation.  If a one-line comment is
-sufficient in those situations, a comment of this form may be used:
+sufficient in those situations, a comment of this form may be used::
 
     /** Handle errors */
     error_callback: function(err) {
@@ -174,7 +174,7 @@
     }
 
 Most functions (or methods) will call for normal, multi-line YUIDoc
-comments like this:
+comments like this::
 
     /**
      * Frob the thingy.
@@ -184,5 +184,5 @@
      * @return {undefined} Side-effects only, eturns nothing.
      */
 
-Full documentation for the various YUIDoc directives is at
-http://yui.github.com/yuidoc/syntax/ .
+`Full documentation <http://yui.github.com/yuidoc/syntax/>`_
+for the various YUIDoc directives is available.