Update README and better divide inclusion into main docs
* Clean up README * Add some info for developers/unit tests/support to README for GitHub * Split up inclusion of contents from README Change-Id: I91abfedce06827d5111370750c55384d7aff1a8e
This commit is contained in:
parent
34c72e9e39
commit
dd9c80d3fe
186
README.rst
186
README.rst
|
@ -1,20 +1,132 @@
|
||||||
README
|
|
||||||
======
|
|
||||||
|
|
||||||
What is git-upstream?
|
What is git-upstream?
|
||||||
---------------------
|
=====================
|
||||||
|
|
||||||
git-upstream is an open source Python application that can be used to
|
Git-upstream is an open source Python application that can be used to
|
||||||
keep in sync with upstream open source projects, mainly OpenStack.
|
keep in sync with upstream open source projects. Its goal is to help
|
||||||
|
manage automatically dropping carried patches when syncing with the
|
||||||
|
project upstream, in a manner transparent to local developers.
|
||||||
|
|
||||||
The main usecase for this tool is for people who are doing active
|
It was initially developed as a tool for people who are doing active
|
||||||
contributions to repositories that are mirrors of OpenStack
|
contributions to local mirrors of projects hosted using Gerrit for code
|
||||||
repositories, with the intention that most of those contributions will
|
review, with the intention that the local changes would be submitted to
|
||||||
be submitted to review.openstack.org at some point. If you are running a
|
the upstream Gerrit instance (review.openstack.org for OpenStack) in
|
||||||
public cloud based on OpenStack, having local changes needed to use it
|
the future, and would subsequent appear in the upstream mainline.
|
||||||
in your environment, you can use git-upstream to stay up to date with
|
|
||||||
the upstream master in a easier way (with respect to using raw git
|
As it uses git plumbing commands, it can identify identical patches
|
||||||
commands).
|
exactly the same as how ``git-rebase`` works, and is not limited to
|
||||||
|
working with Gerrit hosted projects. It can be used with projects
|
||||||
|
hosted in GitHub or any other git repo hosting software.
|
||||||
|
|
||||||
|
Online documentation:
|
||||||
|
|
||||||
|
* http://git-upstream.readthedocs.io/en/latest/
|
||||||
|
|
||||||
|
To install:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
pip install git-upstream
|
||||||
|
|
||||||
|
See also https://pypi.python.org/pypi/git-upstream
|
||||||
|
|
||||||
|
|
||||||
|
You can also install directly from source:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
git clone https://git.openstack.org/openstack/git-upstream.git
|
||||||
|
cd git-upstream
|
||||||
|
pip install .
|
||||||
|
|
||||||
|
Developers
|
||||||
|
----------
|
||||||
|
|
||||||
|
Bug reports:
|
||||||
|
|
||||||
|
* https://bugs.launchpad.net/git-upstream
|
||||||
|
|
||||||
|
Repository:
|
||||||
|
|
||||||
|
* https://git.openstack.org/cgit/openstack/git-upstream
|
||||||
|
|
||||||
|
Cloning:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
git clone https://git.openstack.org/cgit/openstack/git-upstream
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
git clone https://github.com/openstack/git-upstream
|
||||||
|
|
||||||
|
A virtual environment is recommended for development. For example,
|
||||||
|
git-upstream may be installed from the top level directory:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
virtualenv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
pip install -r test-requirements.txt -e .
|
||||||
|
|
||||||
|
|
||||||
|
Patches are submitted via Gerrit at:
|
||||||
|
|
||||||
|
* https://review.openstack.org/
|
||||||
|
|
||||||
|
Please do not submit GitHub pull requests, they will be automatically closed.
|
||||||
|
|
||||||
|
More details on how you can contribute is available on our wiki at:
|
||||||
|
|
||||||
|
* http://docs.openstack.org/infra/manual/developers.html
|
||||||
|
|
||||||
|
Writing a patch
|
||||||
|
---------------
|
||||||
|
|
||||||
|
All code submissions must be pep8_ and pyflakes_ clean. CI will
|
||||||
|
automatically reject them if they are not. The easiest way to do
|
||||||
|
that is to run tox_ before submitting code for review in Gerrit.
|
||||||
|
It will run ``pep8`` and ``pyflakes`` in the same manner as the
|
||||||
|
automated test suite that will run on proposed patchsets.
|
||||||
|
|
||||||
|
Unit Tests
|
||||||
|
----------
|
||||||
|
|
||||||
|
Unit tests have been included and are in the ``git_upstream/tests``
|
||||||
|
folder. Many unit tests samples are included as example scenarios in
|
||||||
|
our documentation to help explain how git-upstream handles various use
|
||||||
|
cases. To run the unit tests, execute the command:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
tox -e py34,py27
|
||||||
|
|
||||||
|
* Note: View ``tox.ini`` to run tests on other versions of Python,
|
||||||
|
generating the documentation and additionally for any special notes
|
||||||
|
on building one of the scenarios to allow direct inspection and
|
||||||
|
manual execution of ``git-upstream`` with various scenarios.
|
||||||
|
|
||||||
|
The unit tests can in many cases be better understood as being closer
|
||||||
|
to functional tests.
|
||||||
|
|
||||||
|
Support
|
||||||
|
-------
|
||||||
|
|
||||||
|
The git-upstream community is found on the `#git-upstream channel on
|
||||||
|
chat.freenode.net <irc://chat.freenode.net/#git-upstream>`_
|
||||||
|
|
||||||
|
You can also join via this `IRC URL
|
||||||
|
<irc://chat.freenode.net/#git-upstream>`_ or use the `Freenode IRC
|
||||||
|
webchat <https://webchat.freenode.net/>`_.
|
||||||
|
|
||||||
|
|
||||||
|
.. _pep8: https://pypi.python.org/pypi/pep8
|
||||||
|
.. _pyflakes: https://pypi.python.org/pypi/pyflakes
|
||||||
|
.. _tox: https://testrun.org/tox
|
||||||
|
|
||||||
|
What does git-upstream do?
|
||||||
|
--------------------------
|
||||||
|
|
||||||
git-upstream provides new git subcommands to support rebasing of
|
git-upstream provides new git subcommands to support rebasing of
|
||||||
local-carried patches on top of upstream repositories. It provides
|
local-carried patches on top of upstream repositories. It provides
|
||||||
|
@ -22,8 +134,9 @@ commands to ease the use of git for who needs to integrate big upstream
|
||||||
projects in their environment. The operations are performed using Git
|
projects in their environment. The operations are performed using Git
|
||||||
commands.
|
commands.
|
||||||
|
|
||||||
.. note:: currently git-upstream can be used only for projects that are
|
.. note:: Currently git-upstream works best for projects that are
|
||||||
maintained with Gerrit as it relies on the presence of Change-IDs.
|
maintained with Gerrit because the presence of Change-Ids allows
|
||||||
|
for fully automated dropping of changes that appear upstream.
|
||||||
Nevertheless, the code is quite modular and can be extended to use
|
Nevertheless, the code is quite modular and can be extended to use
|
||||||
any part of commit message (e.g., other headers).
|
any part of commit message (e.g., other headers).
|
||||||
|
|
||||||
|
@ -82,44 +195,6 @@ were ported to the internal as well. While the original change will be
|
||||||
automatically dropped, also useful to drop the additional ported changes
|
automatically dropped, also useful to drop the additional ported changes
|
||||||
automatically if possible, rather than have it cause conflicts.
|
automatically if possible, rather than have it cause conflicts.
|
||||||
|
|
||||||
What git-upstream is not
|
|
||||||
------------------------
|
|
||||||
|
|
||||||
The name of this tool includes the "git-" prefix because of the Git
|
|
||||||
naming convention that a Git subcommand must have. So, as git-review
|
|
||||||
(usually invoked with "git review [...]"), this tool can be invoked
|
|
||||||
using "git upstream [...]".
|
|
||||||
|
|
||||||
That said, and even if git-upstream currently uses Change-Ids, it is not
|
|
||||||
strictly related to git-review. In other words, git-review can (and most
|
|
||||||
of the time will) be used without even knowing about git-upstream
|
|
||||||
existence.
|
|
||||||
|
|
||||||
Installation
|
|
||||||
============
|
|
||||||
|
|
||||||
At the time of writing, there are two ways to install git-upstream:
|
|
||||||
cloning its git repository or using pip.
|
|
||||||
|
|
||||||
Installing from git repository
|
|
||||||
------------------------------
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
git clone https://git.openstack.org/openstack/git-upstream.git
|
|
||||||
cd git-upstream
|
|
||||||
# Install git-upstream itself
|
|
||||||
python setup.py install
|
|
||||||
|
|
||||||
Installing from PyPI
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
.. code:: bash
|
|
||||||
|
|
||||||
pip install git-upstream
|
|
||||||
|
|
||||||
See also https://pypi.python.org/pypi/git-upstream
|
|
||||||
|
|
||||||
Using git-upstream
|
Using git-upstream
|
||||||
==================
|
==================
|
||||||
|
|
||||||
|
@ -133,7 +208,8 @@ Please see `subcommands <doc/source/subcommands.rst>`_
|
||||||
Authors
|
Authors
|
||||||
=======
|
=======
|
||||||
|
|
||||||
git-upstream was written by Darragh Bailey dbailey@hpe.com.
|
git-upstream was initially written by Darragh Bailey dbailey@hpe.com.
|
||||||
|
See AUTHORS file for other contributors.
|
||||||
|
|
||||||
Acknowledgements
|
Acknowledgements
|
||||||
================
|
================
|
||||||
|
|
|
@ -7,14 +7,20 @@ Welcome to git-upstream's documentation!
|
||||||
========================================
|
========================================
|
||||||
|
|
||||||
.. include:: ../../README.rst
|
.. include:: ../../README.rst
|
||||||
:start-after: ======
|
:start-after: =====================
|
||||||
:end-before: git-upstream installation
|
:end-before: To install:
|
||||||
|
|
||||||
|
.. include:: ../../README.rst
|
||||||
|
:start-after: pip install .
|
||||||
|
:end-before: What does git-upstream do?
|
||||||
|
|
||||||
Contents:
|
Contents:
|
||||||
=========
|
=========
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
|
intro
|
||||||
installation
|
installation
|
||||||
subcommands
|
subcommands
|
||||||
workflows
|
workflows
|
||||||
|
|
|
@ -0,0 +1,8 @@
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
What does git-upstream do?
|
||||||
|
--------------------------
|
||||||
|
.. include:: ../../README.rst
|
||||||
|
:start-after: --------------------------
|
||||||
|
:end-before: Using git-upstream
|
Loading…
Reference in New Issue