==============
Releasing eggs
==============

Introduction
============

We maintain two egg distributions:

1. Quaive private enterprise edition on pypi.quaive.net

2. Ploneintranet community edition on pypi.python.org

Each of those is managed on a separate release branch.

These branches are needed so changes made during the release process
are QA controlled via the normal pull request process.

.. note:: External theme resource package
   Since version 1.2.0a3,
   we depend on the pacakge `quaive.resources.ploneintranet`.

.. note:: Changelog
   Since version 1.2.69 we maintain the changelog manually,
   see https://github.com/quaive/ploneintranet/issues/1416 for details.

Creating a release
==================

This shows how to cut a private release from master.

First, create a release branch from master::

    user@host:~$ git checkout master
    user@host:~$ git pull origin master
    user@host:~$ git switch -c release-x.y.z

You may need to work around `zestreleaser.towncrier breakage`_::

    user@host:~$ . bin/activate

.. _zestreleaser.towncrier breakage: https://github.com/collective/zestreleaser.towncrier/issues/6

Remember tat you need to have ``zestreleaser.towncrier`` installed as well!

Now you can start the release process::

    user@host:~$ bin/prerelease
    Run pyroma on the package before tagging? (Y/n)?
    INFO: ------------------------------
    INFO: Checking /home/ale/Code/plone/ploneintranet
    INFO: Found ploneintranet
    INFO: ------------------------------
    INFO: Final rating: 10/10
    INFO: Your cheese is so fresh most people think it's a cream: Mascarpone
    INFO: ------------------------------
    Do you want to run check-manifest? (Y/n)?
    lists of files in version control and sdist match
    WARNING: Found more than one file, picked the shortest one to change: CHANGES.md, docs/about/history.rst
    Enter version [5.x.y]:
    INFO: Running command to update news: /home/ale/.local/bin/towncrier --version 5.x.y --yes
    Loading template...
    Finding news fragments...
    Rendering news fragments...
    Writing to newsfile...
    Staging newsfile...
    Removing news fragments...
    Removing the following files:
    /.../ploneintranet/news/...
    ...
    Done!

Be sure that ``pyroma`` returns you a rating of 10/10 and that ``check-manifest``
reports "lists of files in version control and sdist match".

If not please fix this.

Also check that the changelog file (``CHANGES.md``) contains
valuable informations and it is readable and that the news folder is empty.

Commit your changes and continue::

    user@host:~$ bin/release
    INFO: Starting release.
    Tag needed to proceed, you can use the following command:
    git tag 5.x.y -m "Tagging 5.x.y"
    Run this command (Y/n)? Y
    Check out the tag (for tweaks or pypi/distutils server upload) (Y/n)? Y
    Register and upload to pypi (Y/n)? n
    Register and upload to quaive (Y/n)? Y
    Register and upload to cosent (Y/n)? n

Please make sure to *not* push a private release to pypi.python.org!

The new release is now available on pypi.quaive.net


Now push your commit::

    user@host:~$ bin/postrelease
    INFO: Starting postrelease.
    Enter new development version ('.dev0' will be appended) [5.x.y+1]:
    OK to commit this (Y/n)? Y
    OK to push commits to the server? (Y/n)? Y


Merge the release changes
-------------------------

Please submit a new pull request from the release branch into master
(go to
https://github.com/quaive/ploneintranet/compare/release-x.y.z?expand=1).
You can delete the ``release-x.y.z`` branch, it can be re-created for a following release.

See :doc:`gitflow` for a full description of the Git workflow.

Using a private egg release
===========================

Prepare your ``~/.pypirc`` that contains the instructions
to authenticate to the private egg repository::

  [distutils]
  index-servers =
      quaive

  [quaive]
  repository=http://pypi.quaive.net
  username=foouser
  password=barpassword
  realm=http://pypi.quaive.net/


Add the this line to your ``buildout.cfg``::

  [buildout]
  ...
  find-links +=
      http://pypi.quaive.net/packages/


If you want to install the latest ploneintranet alpha/beta releases add::

  [buildout]
  ...
  prefer-final = false

or pin the ploneintranet version you desire, e.g.::

  [versions]
  ...
  ploneintranet = 5.x.y

Instead of creating a ``~/.pypirc`` file,
you can add the credentials to the URL in the ``find-links`` option, e.g.:
http://foouser:barpassword@pypi.quaive.net/packages/.
In this case remember to keep the file safe :)

You can use the `saturn` egg based deployment as a template.


Update `quaive.resources.ploneintranet`
=======================================

This process requires to clone separately `quaive.resources.ploneintranet`
and releasing it to `pypi.quaive.net`::

  git clone git@github.com:quaive/quaive.resources.ploneintranet.git
  cd quaive.resources.ploneintranet
  make all
  fullrelease

Take note of the released egg version,
and update the file `buildout.d/versions.cfg`
in order to match it, e.g.::

  [versions]
  # Quaive packages
  quaive.resources.ploneintranet = 9.x.y

Make a pull request to `quaive/ploneintranet` with this changes.


Managing users on pypi.quaive.net
=================================

You can only add users if you have shell access::

    user@host$ ssh pypi@pypi.quaive.net
    pypi@cs02:~$ cd pypiserver/
    pypi@cs02:~/pypiserver$ htpasswd var/quaive/htpasswd.txt johndoe
    New password:
    Re-type new password:
    Adding password for user johndoe

Ask Guido to add your users if you do not have ssh access.
