Merge "Update README and better divide inclusion into main docs"
This commit is contained in:
commit
fe410ecf2f
186
README.rst
186
README.rst
|
@ -1,20 +1,132 @@
|
|||
README
|
||||
======
|
||||
|
||||
What is git-upstream?
|
||||
---------------------
|
||||
=====================
|
||||
|
||||
git-upstream is an open source Python application that can be used to
|
||||
keep in sync with upstream open source projects, mainly OpenStack.
|
||||
Git-upstream is an open source Python application that can be used to
|
||||
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
|
||||
contributions to repositories that are mirrors of OpenStack
|
||||
repositories, with the intention that most of those contributions will
|
||||
be submitted to review.openstack.org at some point. If you are running a
|
||||
public cloud based on OpenStack, having local changes needed to use it
|
||||
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
|
||||
commands).
|
||||
It was initially developed as a tool for people who are doing active
|
||||
contributions to local mirrors of projects hosted using Gerrit for code
|
||||
review, with the intention that the local changes would be submitted to
|
||||
the upstream Gerrit instance (review.openstack.org for OpenStack) in
|
||||
the future, and would subsequent appear in the upstream mainline.
|
||||
|
||||
As it uses git plumbing commands, it can identify identical patches
|
||||
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
|
||||
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
|
||||
commands.
|
||||
|
||||
.. note:: currently git-upstream can be used only for projects that are
|
||||
maintained with Gerrit as it relies on the presence of Change-IDs.
|
||||
.. note:: Currently git-upstream works best for projects that are
|
||||
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
|
||||
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 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
|
||||
==================
|
||||
|
||||
|
@ -133,7 +208,8 @@ Please see `subcommands <doc/source/subcommands.rst>`_
|
|||
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
|
||||
================
|
||||
|
|
|
@ -7,14 +7,20 @@ Welcome to git-upstream's documentation!
|
|||
========================================
|
||||
|
||||
.. include:: ../../README.rst
|
||||
:start-after: ======
|
||||
:end-before: git-upstream installation
|
||||
:start-after: =====================
|
||||
:end-before: To install:
|
||||
|
||||
.. include:: ../../README.rst
|
||||
:start-after: pip install .
|
||||
:end-before: What does git-upstream do?
|
||||
|
||||
Contents:
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro
|
||||
installation
|
||||
subcommands
|
||||
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