~inetpro/ubuntu-africa/build-instructions

.. title: Build Instructions
.. slug: build-instructions
.. date: 2015-04-06 12:09:11 UTC
.. tags: 
.. category: 
.. link: 
.. description: 
.. type: text

.. sectnum::

.. class:: alert alert-info pull-right

.. contents:: Table of Contents
   :depth: 2

Quick Background
================

The Ubuntu Africa site is a static HTML site generated by the `Nikola <http://getnikola.com/>`_ site generator. Content is written using `reStructuredText <http://docutils.sourceforge.net/rst.html>`_, an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system, a component of `Docutils <http://docutils.sourceforge.net/index.html>`_. Nikola is written in Python and is in the Ubuntu repositories.

.. note:: 

   Nikola version 7.3 or higher is required

The tutorial below will show you how to checkout, modify, commit, and propose a merge for the Ubuntu Africa web site. While these instructions are specific about the site, they will work for almost any other project on `Launchpad <https://launchpad.net/>`_.

Our QA site is available at: http://ubuntu-africa.snyman.info/

Build Environment (Simple Method)
=================================

Packages to install
-------------------

::

    $ sudo apt-get install bzr qbzr python-virtualenv python-webassets python-dev

Make a virtual environment
--------------------------

virtualenv is a tool to create isolated Python virtual environments and creates a folder which contains all the necessary executables to use the packages that a Python project would need. `More... <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_

::

    $ virtualenv --system-site-packages ~/virtualenv
    $ ~/virtualenv/bin/pip install --upgrade nikola

This allows you to run Nikola like so:

::

    $ ~/virtualenv/bin/nikola build

Set up an alias (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~

Edit your .bashrc file and add the following line:

::

    alias activate_nikola="source ~/virtualenv/bin/activate"

Then you can simply activate your virtual environment and use Nikola like so:

::

    $ activate_nikola
    $ nikola build

To deactivate, simply type in "deactivate":

::

    $ deactivate

Build Environment (Alternative / Longer Method)
===============================================

Packages to install
-------------------

::

    $ sudo apt-get install bzr git libxml2-dev libxslt1-dev python-dateutil python-dev python-pygments python-virtualenv zlib1g-dev qbzr 

Make a virtual environment
--------------------------

`pyenv install instructions <https://github.com/alanorth/nairobilug.or.ke/blob/9e8ec6fb9240b03dea74dada1a6d3a0af752057b/README.md>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    $ git clone https://github.com/yyuu/pyenv.git ~/.pyenv
    $ git clone https://github.com/yyuu/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

Use editor of your choice to add following lines to end of ~/.bashrc
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    # Enable pyenv
    # See: https://github.com/yyuu/pyenv#basic-github-checkout
    if [[ -d ~/.pyenv ]]; then
      export PYENV_ROOT="$HOME/.pyenv"
      export PATH="$PYENV_ROOT/bin:$PATH"

      eval "$(pyenv init -)"
      # optionally enable pyenv-virtualenv
      # See: https://github.com/yyuu/pyenv-virtualenv
      if [[ -d ~/.pyenv/plugins/pyenv-virtualenv ]]; then
        eval "$(pyenv virtualenv-init -)"
      fi
    fi

Read and execute commands from modified ~/.bashrc
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    $ source ~/.bashrc

Setup Projects folder and nikola environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

    $ pyenv virtualenv Nikola
    $ pyenv activate Nikola
    $ pip install --upgrade nikola
    $ pip install webassets
    $ nikola version

Bazaar Project Checkout and Testing
===================================

-  `Bazaar User Guide <http://doc.bazaar.canonical.com/latest/en/user-guide/index.html>`_
-  `Bazaar in five minutes <http://doc.bazaar.canonical.com/latest/en/mini-tutorial/>`_

Initialise Bazaar environment
-----------------------------

If you don't have an account on Launchpad.net, go to `<https://launchpad.net/+login>`_ to create one and log in. Once logged in, you'll need to make sure you have your SSH public key uploaded to your account at https://launchpad.net/people/+me/+editsshkeys. See `Creating an SSH Key Pair <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_ for more info. 

You need to configure Bazaar with your name and email address so that your commits can be identified. You should use your email address which is registered on Launchpad::

    $ bzr whoami "MyName MySurname <MyEmail@address.com>"
    $ bzr launchpad-login MyLaunchPadID
    $ bzr launchpad-login

Checkout latest code and test with Nikola
-----------------------------------------

::

    $ mkdir ~/Projects && cd ~/Projects
    $ bzr init-repo ubuntu-africa
    $ cd ~/Projects/ubuntu-africa
    $ bzr co lp:ubuntu-africa trunk
    $ cd ~/Projects/ubuntu-africa/trunk/
    $ nikola build && nikola serve

Create your own Branch
~~~~~~~~~~~~~~~~~~~~~~

In order to work on the project you need to create branches to do the work in, edit and commit your changes and then push your local branch up to Launchpad, and then propose a merge, and finally merge your changes in to the main branch.

.. note::

    You can see the history of a branch by browsing its log with `bzr log`.
    
    Once you have completed some work, it’s a good idea to review your changes prior to permanently recording it. This way, you can make sure you’ll be committing what you intend to. 
    
    Two bzr commands are particularly useful here: **status** and **diff**.

::

    $ cd ~/Projects/ubuntu-africa
    $ bzr branch trunk new-feature-page
    $ cd new-feature-page

Make your edits
~~~~~~~~~~~~~~~

::

    $ nikola new_page
    ....
    Title: New Feature
    ....
    $ vim pages/new-feature.rst
    $ bzr add
    adding pages/new-feature.rst

Commit your edits
~~~~~~~~~~~~~~~~~

::

    $ bzr commit -m "Added a new-feature page"
    Committing to: ~/Projects/ubuntu-africa/new-feature-page/
    added pages/new-feature.rst
    Committed revision ##.

Push a Branch
-------------

In order to have your branch visible to the other developers, and in order to propose a merge, you need to push it up to Launchpad. This will create a remote branch on Launchpad, identical to your local branch.::

    $ bzr push lp:~MyLaunchPadID/ubuntu-africa/new-feature-page
    Using default stacking branch /+branch-id/######## at chroot-#####:///~MyLaunchPadID/ubuntu-africa/
    Created new stacked branch referring to /+branch-id/########.

Propose a Merge
---------------

Go to your code page on Launchpad at ``https://code.launchpad.net/~MyLaunchPadID`` or to the main `Ubuntu Africa Project Code Page <https://code.launchpad.net/ubuntu-africa>`_, click on your branch in the list and then click on "Propose a Merge" or ask others to review your code before requesting a merge proposal.

Merging
-------

.. attention::

    Merging into trunk is done by the core developers. If you are not a core developer, you won't be able to commit to trunk.

In your local ``trunk`` directory, run the merge command::
    
    $ bzr merge lp:~john-doe/ubuntu-africa/new-contact-page
    +N  pages/contact.rst                                                                                                                      
    All changes applied successfully.
    
This merges the changes from that remote branch into your local files. Now you need to commit those changes into the repository, which will send them up to the main branch::
    
    $ bzr commit -m "Add a new contact page" --author="John Doe <john.doe@example.com>"
    
Once again, you need to specify a commit message (usually just a copy of the merge proposal message or the last commit message in the remote branch), and the author of the commit. This author flag gives credit to the original author of the changes, even if they do not have permission to write to the main repository. Give credit where credit is due.

Update your local copy with changes made by others
--------------------------------------------------

One of the important aspects of working with others in a team is keeping your checkout up to date with the latest changes made by others to the central trunk.::

    $ cd ~/Projects/ubuntu-africa/trunk/
    $ bzr update