==================
Recreating Content
==================

When the algorithms in ``compare-locales`` get updated, it might be necessary
to explicitly update the current state of the gecko-strings repository.

This is also a good way to drop branches or projects, and similar configuration
changes. Adding a new branch should work without this step.

The ``force`` cli tool is helpful in these cases. This tool creates the
content for one source repository for all branches in the configuration
:py:mod:`initial.cli._config`, for the revisions from the last conversion.
As such it should only produce differences for changing configurations and
the content generation toolchain. As it doesn't know about what changed,
or if, it doesn't remove content nor commits to VCS. Depending on the expected
results, one may need to remove files in the target repository before running
the tool.

.. note:: This tool is a blunt knife, handle with care.


Example:

.. code-block:: bash

   python -m initial.cli.force ~/src/mozilla-central ../output
   python -m initial.cli.force ~/src/comm-central ../output

You want to commit the results in the target repository.

To create good commit messages, it's recommended to have the first line
to describe the change, and to ammend the commit message with the meta
data associated with the state we converted. You find the right data in
the target repository with either

.. code-block:: bash

   hg log -r 'limit(reverse(desc("mozilla-central")))' -v|grep X-C|sed -e's/-Converted//g'

or

.. code-block:: bash

   hg log -r 'limit(reverse(desc("comm-central")))' -v|grep X-C|sed -e's/-Converted//g'

You want to create separate commits for each repository.

Obviously, you want to rigorously review the changes, and the next few future
updates.

Updating compare-locales
========================

This should not change the set of files, nor the created project config files,
so the above steps are all you need.

Dropping Projects
=================

Before recreating the content, remove all affected project config files, and
target localization files. You can be generous here, as the ``force`` command
will recreate the files that are supposed to still be there.

Dropping Branches
=================

Before recreating the content, remove all target translation files. When
copying over the meta data from existing meta data, only copy those
repositories and revisions that remain active.