launchpad-reviewers team mailing list archive

[Ines Almeida <mp+444865@xxxxxxxxxxxxxxxxxx>]

Ines Almeida has proposed merging ~ines-almeida/launchpad:add-doc-publishing-tarball into launchpad:master.

Commit message:
Add documentation page on how to publish artifacts

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~ines-almeida/launchpad/+git/launchpad/+merge/444865

I added it as an how-to because that's what it felt like it was when writing. Happy to change it!
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~ines-almeida/launchpad:add-doc-publishing-tarball into launchpad:master.

diff --git a/doc/explanation/charms.rst b/doc/explanation/charms.rst
index d943072..4fca9d7 100644
--- a/doc/explanation/charms.rst
+++ b/doc/explanation/charms.rst
@@ -116,9 +116,12 @@ these guidelines to build your charm for Launchpad:
 3. **Write minimal code:** You can start by writing minimal reactive code
    that gets the source tree deployed (nothing too specialized).
    This should give you something you can build and deploy to a Juju model to
-   test out. (Tip: have a look at ``charm/launchpad/`` charm. It can be used as a
-   minimal skeleton that does nothing except deploy a Launchpad payload with
+   test out. (Tip: have a look at ``charm/launchpad/`` charm. It can be used as
+   a minimal skeleton that does nothing except deploy a Launchpad payload with
    some basic configuration).
+   If your application doesn't publish artifacts that can be used by your charm
+   to deploy the source code, have a look at
+   :ref:`Create Jobs to Publish Artifacts <create_job_to_publish_artifacts>`.
 
 4. **Add configurations:** Have a look at configurations related to your app
    in `lp-production-configs 
diff --git a/doc/how-to/create-job-publish-artifact.rst b/doc/how-to/create-job-publish-artifact.rst
new file mode 100644
index 0000000..5f641f9
--- /dev/null
+++ b/doc/how-to/create-job-publish-artifact.rst
@@ -0,0 +1,71 @@
+
+.. _create_job_to_publish_artifacts:
+
+==============================
+Create job to publish artifact
+==============================
+
+Often we need to publish our project's artifacts so they can be accessed by
+other entities. When building a charm with the launchpad-base layers, for
+example, you will want your code to be published in Swift as a tarball, so
+that the right version of your code is downloaded when building the charm.
+
+We also want the artifact building to be automated. This can be achieved by
+having `Jenkins <https://jenkins.canonical.com/>`_ jobs building your artifact
+on code merge.
+
+
+-------------
+Steps to take
+-------------
+
+1. **Open an IS ticket to create swift credentials for your new project**
+
+   * Your new `IS ticket <https://portal.admin.canonical.com/requests/new>`_
+     should have a title along the lines of `"Swift credentials for
+     <project name> builds"` and have information along the lines of:
+
+        `"We need a new Swift user and project whose credentials we'll
+        give to a Jenkins instance to build deployment artifacts and publish
+        them to PS5 Swift. The user can be named 'stg-<project name>-builds'
+        and the project 'stg-<project name>-builds_project'."`
+
+     Open this ticket as early as possible since it might take a while until
+     IS can go through it.
+
+2. **Create 'build-tarball' and 'publish-tarball' commands in your project's
+   Makefile**
+
+   * The ``build-tarball`` command should rebuild the virtual environment anew,
+     create a wheel with all the necessary dependencies, and then build a
+     tarball into a given path (``build/<commit-id>/<name-of-tar>.tar.gz`` for
+     example) - see existing examples in the Launchpad suite!
+
+   * For the publishing, copy ``publish-to-swift.py`` script (found in a few
+     launchpad projects including launchpad-itself) to your project's
+     directory. The ``publish-tarball`` command should be dependent on
+     ``build-tarball`` and should run the ``publish-to-swift`` script - again
+     see existing examples.
+
+3. **Create or update jenkins job to run the publishing command**
+
+   * Check if there is already a file for your project within the
+     `ols-jenkaas <https://code.launchpad.net/ols-jenkaas>`_ repo in the
+     ``/jobs`` folder. If there isn't, create one based on an existing one.
+
+   * The important sections to make the job publish your tarball are the
+     ``build-command`` - it should run your ``make publish-tarball`` command -
+     and the ``jobs`` list, which should have at least the
+     ``{name}-build-charm`` and ``trigger-{name}-build-charm-on-changes``.
+
+4. **Get the new credentials into Jenkins**
+
+   * Someone responsible for Jenkins (ask IS or team) will need to add the
+     new credentials IS created to your Jenkins jobs.
+   * After IS creates your credentials, you can find them by SSH'ing into
+     ``launchpad-bastion-ps5``, assuming the new role IS created and running
+     ``load_creds openstack``.
+     This will load your credentials into your environmental variables (run
+     ``env`` to list all env variables). To share them, with the person
+     responsible, ask what they might need. The most relevant credentials are
+     ``OS_USERNAME``, ``OS_TENANT_NAME`` and ``OS_PASSWORD``.
diff --git a/doc/how-to/index.rst b/doc/how-to/index.rst
index ea7b441..892fcf3 100644
--- a/doc/how-to/index.rst
+++ b/doc/how-to/index.rst
@@ -26,6 +26,7 @@ Common development tasks
    update-configuration-for-testing
    doc-theme
    testing-scripts
+   create-job-publish-artifact
 
 Operating development instances
 -------------------------------