Merge lp:~adam-collard/juju-core/writing-charms-typos into lp:juju-core/docs

Proposed by Adam Collard on 2013-10-03
Status: Merged
Approved by: Nick Veitch on 2013-10-03
Approved revision: 143
Merged at revision: 139
Proposed branch: lp:~adam-collard/juju-core/writing-charms-typos
Merge into: lp:juju-core/docs
Diff against target: 110 lines (+19/-19)
1 file modified
htmldocs/authors-charm-writing.html (+19/-19)
To merge this branch: bzr merge lp:~adam-collard/juju-core/writing-charms-typos
Reviewer Review Type Date Requested Status
charmers 2013-10-03 Pending
Review via email: mp+188994@code.launchpad.net

Description of the change

Clean up examples and fix some capitalisation/spelling problems in Charm writing.

I found more issues as I started looking into the one bug, I've bundled them all into this MP - I can split them out if necessary.

To post a comment you must log in.
142. By Adam Collard on 2013-10-03

Capitalise sentence.

143. By Adam Collard on 2013-10-03

More cleanups:
 * Capitalisation of sentences.
 * s/apache/Apache/
 * s/apache webservice/Apache web server/
 * Paragaph break
 * Add missing )

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'htmldocs/authors-charm-writing.html'
2--- htmldocs/authors-charm-writing.html 2013-09-27 14:53:30 +0000
3+++ htmldocs/authors-charm-writing.html 2013-10-03 07:29:46 +0000
4@@ -114,7 +114,7 @@
5 <div class="step" id="step03">
6 <h2>Make some metadata.yaml</h2>
7 <p>The <strong>metadata.yaml</strong> file is really important. This is the file that Juju reads to find out what a charm is, what it does and what it needs to do it.</p>
8- <p>The yaml syntax is at once simple, but exact, so if you have any future problems with Juju not recognising your charm, this is the first port of call! the information is stored in simple <span class="pre">&LT;key&GT; : &LT;value&GT;</span> associations. The first four are pretty self explanitory:</p>
9+ <p>The YAML syntax is at once simple, but exact, so if you have any future problems with Juju not recognising your charm, this is the first port of call! The information is stored in simple <span class="pre">&LT;key&GT; : &LT;value&GT;</span> associations. The first four are pretty self explanatory:</p>
10 <pre class="prettyprint lang-yaml">
11 name: vanilla
12 summary: Vanilla is an open-source, pluggable, multi-lingual forum.
13@@ -125,19 +125,19 @@
14 installation guide.
15 </pre>
16 <p>The summary should be a brief description of the service being deployed, whereas the description can go into more detail.</p>
17- <p>The next value to define is the category. This is primarily for organising the charm in the charm store. the available categories are:</p>
18+ <p>The next value to define is the category. This is primarily for organising the charm in the charm store. The available categories are:</p>
19 <ul>
20- <li><strong>databases -</strong> MySQL, Postgres, couchDB, etc.</li>
21- <li><strong>file-servers - </strong>storage apps such as ceph</li>
22- <li><strong>applications -</strong>applications like mediawiki, wordpress</li>
23- <li><strong>cache-proxy - </strong>services such as haproxy and Varnish.</li>
24+ <li><strong>databases -</strong> MySQL, PostgreSQL, CouchDB, etc.</li>
25+ <li><strong>file-servers - </strong>storage apps such as Ceph</li>
26+ <li><strong>applications -</strong>applications like MediaWiki, WordPress</li>
27+ <li><strong>cache-proxy - </strong>services such as HAProxy and Varnish.</li>
28 <li><strong>app-servers - </strong>infrastructure services like Apache and Tomcat</li>
29 <li><strong>miscellaneous - </strong>anything which doesn't neatly fit anywhere above.</li>
30 </ul>
31- <p>Your charm can belong to more than one category, though in almost all cases it should be in just one. Because there could be more than one entry here, the yaml is formatted as a list:</p>
32+ <p>Your charm can belong to more than one category, though in almost all cases it should be in just one. Because there could be more than one entry here, the YAML is formatted as a list:</p>
33 <pre class="prettyprint lang-yaml">categories:<br> - applications</pre>
34 <p>Next we need to explain which services are actually provided by this service. This is done using an indent for each service provided, followed by a description of the interface. The interface name is important as it can be used elsewhere in the environment to relate back to this charm, e.g. when writing hooks.</p>
35- <p>Our Vanilla charm is a web-based service which exposes a simple http interface:</p>
36+ <p>Our Vanilla charm is a web-based service which exposes a simple HTTP interface:</p>
37 <pre class="prettyprint lang-yaml">provides:<br> website:<br> interface: http</pre>
38 <p>The name given here is important as it will be used in hooks that we write later, and the interface name will be used by other charms which may want to relate to this one.</p>
39 <p>Similarly we also need to provide a "requires" section. In this case we need a database. Checking out the metadata of the MySQL charm we can see that it provides this via the interface name "mysql", so we can use this name in our metadata.</p>
40@@ -178,15 +178,15 @@
41 <p>So first up we should create the hooks directory, and start creating our first hook:</p>
42 <pre>mkdir hooks<br>cd hooks<br>vi start</pre>
43 <p>(Use your favourite editor, naturally - no flames please)</p>
44- <p>We have started with the start hook, because it is pretty simple. Our charm will be served up by apache, so all we need to do to start the service is make sure apache is running:</p>
45+ <p>We have started with the start hook, because it is pretty simple. Our charm will be served up by Apache, so all we need to do to start the service is make sure Apache is running:</p>
46 <pre class="prettyprint lang-bash">#!/bin/bash<br>set -e<br>service apache2 restart</pre>
47 <p>A bit of explanation for this one. As we are writing in bash, and we need the files to be executable, we start with a hash-bang line indicating this is a bash file.
48 the <span class="pre">set -e</span> line means that if any subsequent command returns false (non-zero) the script will stop and raise an error - this is important so that Juju can work out if things are running properly.
49 </p>
50- <p>The final line starts the apache webservice, thus also starting our Vanilla service. Why do we call 'restart'? One of the important ideas behind hooks is that they should be 'idempotent'. That means that the opration should be capable of being run many times without changing the intended result (basically). in this case, we don't want an error if apache is actually already running, we just want it to run and reload any config changes.</p>
51+ <p>The final line starts the Apache web server, thus also starting our Vanilla service. Why do we call 'restart'? One of the important ideas behind hooks is that they should be 'idempotent'. That means that the operation should be capable of being run many times without changing the intended result (basically). In this case, we don't want an error if Apache is actually already running, we just want it to run and reload any config changes.</p>
52 <p>Once you have saved the file, it is important to make sure that you set it to be executable too!</p>
53 <pre>chmod +x start</pre>
54- <p>With the easy bit out of the way, how about the install hook? This needs to install any dependencies, fetch the actual software and do any other config and service jobs that need to happen. here is an example for our vanilla charm:</p>
55+ <p>With the easy bit out of the way, how about the install hook? This needs to install any dependencies, fetch the actual software and do any other config and service jobs that need to happen. Here is an example for our vanilla charm:</p>
56
57 <pre class="prettyprint">
58 #!/bin/bash
59@@ -219,7 +219,7 @@
60 chmod -R 777 /var/www/vanilla/conf /var/www/vanilla/uploads /var/www/vanilla/cache
61
62 juju-log "Creating apache2 configuration"
63-cat &lt;&lt;EOF $gt; /etc/apache2/sites-available/vanilla
64+cat &lt;&lt;EOF &gt; /etc/apache2/sites-available/vanilla
65 &lt;VirtualHost *:80&gt;
66 ServerAdmin webmaster@localhost
67 DocumentRoot /var/www/vanilla
68@@ -246,9 +246,9 @@
69 juju-log "Files extracted, waiting for other events before we do anything else!"
70 </pre>
71 <p>We aren't going to go for a line-by-line explanation of that, but there are a few things worth noting</p>
72- <p>Firstly, note the use of the -y option of the apt-get command. this assumes a 'yes' answer to any questions and removes any manual install options (e.g. services that run config dialogs when they install</p>
73+ <p>Firstly, note the use of the -y option of the apt-get command. this assumes a 'yes' answer to any questions and removes any manual install options (e.g. services that run config dialogs when they install).</p>
74 <p>In our script, we are fetching the tarball of the Vanilla software. In these cases, it is obviously always better to point to a specific, permanent link to a version of the software. </p>
75- <p>Also, you will notice that we have used the <span class="pre">juju-log</span> command. This basically spits messages out into the juju log, which is very useful for testing and debugging. We will cover that in more detail later in this walkthrough. </p>
76+ <p>Also, you will notice that we have used the <span class="pre">juju-log</span> command. This basically spits messages out into the Juju log, which is very useful for testing and debugging. We will cover that in more detail later in this walkthrough. </p>
77 <p>The next step is to create the relationship hooks... </p>
78 <p>We know from our metadata that we have a connection called 'database', so we can have hooks that relate to that. Note that we don't have to create hooks for all possible events if they are not required - if Juju doesn't find a hook file for a paticular action, it just assumes everything is okay and carries on. It is up to you to decide which events require a hook.</p>
79 <p>Let's take a stab at the 'database-relation-changed' hook:</p>
80@@ -268,8 +268,8 @@
81
82 vanilla_config="/var/www/vanilla/conf/config.php"
83
84-cat <<EOF > $vanilla_config
85-&LT;?php if (!defined('APPLICATION')) exit();
86+cat &lt;&lt;EOF &gt; $vanilla_config
87+&lt;?php if (!defined('APPLICATION')) exit();
88
89 \$Configuration['Database']['Host'] = '$db_host';
90 \$Configuration['Database']['Name'] = '$db_db';
91@@ -292,8 +292,8 @@
92
93 relation-set hostname=`unit-get private-address` port=80
94 </pre>
95-<p>Here we can see the other end of the information sharing - in this case <span class="pre">relation-set</span> exposes the given values to the connecting charm. In this case one of the commands is backticked, as <span class="pre">unit-get</span> is another helper command, in this case one which returns the requested value form the machine the charm is running on, specifically here it's IP address.
96- So, any connecting charm will be able to ask for the values 'hostname' and 'port'. Remember, once you have finished writing your hooks make sure you 'chmod +x' them.</p>
97+<p>Here we can see the other end of the information sharing - in this case <span class="pre">relation-set</span> exposes the given values to the connecting charm. In this case one of the commands is backticked, as <span class="pre">unit-get</span> is another helper command, in this case one which returns the requested value form the machine the charm is running on, specifically here it's IP address.</p>
98+<p>So, any connecting charm will be able to ask for the values 'hostname' and 'port'. Remember, once you have finished writing your hooks make sure you 'chmod +x' them.</p>
99 <p>For our simplistic charm, that is all the hooks we need for the moment, so now we can test it out!</p>
100 </div>
101 <span class="number"> 5 </span>
102@@ -301,7 +301,7 @@
103 <h2>Testing</h2>
104 <p>Before we congratulate ourselves too much, we should check that the charm actually works. To help with this, we should open a new terminal window and run the following command:</p>
105 <pre>juju debug-log</pre>
106- <p>This starts a process to tail the juju log file and show us just exactly what is happening. It won't do much to begin with, but you should see messages appearing when we start to deploy our charm.</p>
107+ <p>This starts a process to tail the Juju log file and show us just exactly what is happening. It won't do much to begin with, but you should see messages appearing when we start to deploy our charm.</p>
108 <p>Following our own recipe, in another terminal we should now do the following (assuming you already have a bootstrapped environment):</p>
109 <pre>juju deploy mysql
110 juju deploy --repository=/home/evilnick/localcharms/ local:precise/vanilla

Subscribers

People subscribed via source and target branches