diff --git a/README.rst b/README.rst index 678897f..17c11f0 100644 --- a/README.rst +++ b/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 `_ + +You can also join via this `IRC URL +`_ or use the `Freenode IRC +webchat `_. + + +.. _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 `_ 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 ================ diff --git a/doc/source/index.rst b/doc/source/index.rst index 04f451a..a42009a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/intro.rst b/doc/source/intro.rst new file mode 100644 index 0000000..33c89da --- /dev/null +++ b/doc/source/intro.rst @@ -0,0 +1,8 @@ +Introduction +============ + +What does git-upstream do? +-------------------------- +.. include:: ../../README.rst + :start-after: -------------------------- + :end-before: Using git-upstream