| |
@@ -11,23 +11,18 @@
|
| |
|
| |
Libtaskotron is written mostly in `Python <https://www.python.org/>`_.
|
| |
|
| |
- Source code
|
| |
- -----------
|
| |
-
|
| |
- The source code for libtaskotron is available at:
|
| |
- https://pagure.io/taskotron/libtaskotron
|
| |
-
|
| |
- If you submit patches, please use the process of :ref:`submitting-code`.
|
| |
|
| |
.. _taskotron-bugs:
|
| |
|
| |
- Bugs, issues and tasks
|
| |
- ----------------------
|
| |
+ Source code, bugs, tasks
|
| |
+ ------------------------
|
| |
+
|
| |
+ The source code for libtaskotron is available at:
|
| |
+ https://pagure.io/taskotron/libtaskotron
|
| |
|
| |
- We use `Phabricator <http://phabricator.org/>`_ to track issues and facilitate
|
| |
- code reviews for several projects related to libtaskotron and Fedora QA.
|
| |
+ This project is also used to track bugs and tasks.
|
| |
|
| |
- Our phabricator instance can be found at https://phab.qa.fedoraproject.org/
|
| |
+ If you submit patches, please use the process of :ref:`submitting-code`.
|
| |
|
| |
|
| |
.. _running-tests:
|
| |
@@ -36,7 +31,7 @@
|
| |
---------------------------------
|
| |
|
| |
We place a high value on having decent test coverage for the libtaskotron code.
|
| |
- In general, tests are written using `pytest <http://pytest.org/>` and are broken
|
| |
+ In general, tests are written using `pytest <http://pytest.org/>`_ and are broken
|
| |
up into two types:
|
| |
|
| |
* **Unit Tests** test the core logic of code. They do not touch the filesystem
|
| |
@@ -47,13 +42,9 @@
|
| |
tests are often much slower than unit tests but they offer coverage which is
|
| |
not present in the unit tests.
|
| |
|
| |
- To run the unit tests::
|
| |
-
|
| |
- py.test testing/
|
| |
+ To run the unit tests, execute::
|
| |
|
| |
- To run the functional and unit tests::
|
| |
-
|
| |
- py.test -F testing/
|
| |
+ py.test
|
| |
|
| |
|
| |
Continuous integration
|
| |
@@ -82,52 +73,6 @@
|
| |
files automatically cleaned up, so that they don't occupy disk space in vain.
|
| |
There is a tmpfiles.d template prepared for you, look into ``conf/tmpfiles.d``.
|
| |
|
| |
- Support tools
|
| |
- -------------
|
| |
-
|
| |
- There are several tools that, while not required, make the process of developing
|
| |
- for libtaskotron significantly easier.
|
| |
-
|
| |
-
|
| |
- .. _installing-arcanist:
|
| |
-
|
| |
- Arcanist
|
| |
- ^^^^^^^^
|
| |
-
|
| |
- `Arcanist <https://secure.phabricator.com/book/phabricator/article/arcanist/>`_
|
| |
- is a command line interface to Phabricator which can be used to submit code
|
| |
- reviews, download/apply code under review among other useful functions.
|
| |
-
|
| |
- As Arcanist is an interface to Phabricator, we **strongly recommend** that you
|
| |
- install it using our packages instead of from the upstream git repos (as
|
| |
- described in upstream documentation). That way, there is no question that the
|
| |
- Arcanist version used locally is compatible with our Phabricator instance.
|
| |
-
|
| |
- To add our dnf repository containing Phabricator related packages, run::
|
| |
-
|
| |
- sudo curl https://repos.fedorapeople.org/repos/tflink/phabricator/fedora-phabricator.repo \
|
| |
- -o /etc/yum.repos.d/fedora-phabricator.repo
|
| |
-
|
| |
- Once the repository has been configured, install Arcanist using::
|
| |
-
|
| |
- sudo dnf -y install arcanist
|
| |
-
|
| |
- Arcanist is written in PHP and installing it will pull in several PHP packages
|
| |
- as dependencies.
|
| |
-
|
| |
-
|
| |
- .. _installing-gitflow:
|
| |
-
|
| |
- gitflow
|
| |
- ^^^^^^^
|
| |
-
|
| |
- The `gitflow plugin for git <https://github.com/nvie/gitflow>`_ is another
|
| |
- useful, but not required tool that is available in the Fedora repositories.
|
| |
-
|
| |
- To install the gitflow plugin, run::
|
| |
-
|
| |
- sudo dnf -y install gitflow
|
| |
-
|
| |
|
| |
.. _submitting-code:
|
| |
|
| |
@@ -138,9 +83,8 @@
|
| |
branching model and with the exception of hotfixes, all changes made should be
|
| |
against the ``develop`` branch.
|
| |
|
| |
- While not required, using the `gitflow plugin for git <https://github.com/nvie/gitflow>`_
|
| |
- is recommended as it makes the process significantly easier. See
|
| |
- :ref:`installing-gitflow` for instructions on installing gitflow on Fedora.
|
| |
+ If you want to use the `gitflow plugin for git <https://github.com/nvie/gitflow>`_
|
| |
+ to make this process more user-friendly, simply install the ``gitflow`` package.
|
| |
|
| |
|
| |
Start a new feature
|
| |
@@ -148,9 +92,13 @@
|
| |
|
| |
To start work on a new feature, use::
|
| |
|
| |
- git flow feature start TXXX-short-description
|
| |
+ git checkout -b feature/XXX-short-description develop
|
| |
|
| |
- Where ``TXXX`` is the issue number in Phabricator and ``short-description`` is a
|
| |
+ or if you want to use gitflow, use::
|
| |
+
|
| |
+ git flow feature start XXX-short-description
|
| |
+
|
| |
+ where ``XXX`` is the issue number in Pagure and ``short-description`` is a
|
| |
short, human understandable description of the change contained in this branch.
|
| |
|
| |
In general, short reviews are better than long reviews. If you can, please break
|
| |
@@ -160,36 +108,10 @@
|
| |
Submitting code for review
|
| |
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
| |
|
| |
- .. note::
|
| |
-
|
| |
- Make sure to run all unit and functional tests before submitting code for
|
| |
- review. Any code that causes test failure will receive requests to fix the
|
| |
- offending code or will be rejected. See :ref:`running-tests` for information
|
| |
- on running unit and functional tests.
|
| |
-
|
| |
- Code reviews are done through Phabricator, not pull requests. While it is possible
|
| |
- to submit code for review through the web interface, :ref:`installing-arcanist`
|
| |
- is recommended.
|
| |
-
|
| |
- You do not need to push code anywhere public before submitting a review. Unless
|
| |
- there is a good reason to do so (and there are very few), pushing a feature
|
| |
- branch to origin is frowned on as it makes repository maintenance more difficult
|
| |
- for no real benefit.
|
| |
-
|
| |
- To submit code for review, make sure that your code has been updated with respect
|
| |
- to ``origin/develop`` and run the following from your checked-out feature branch::
|
| |
-
|
| |
- arc diff develop
|
| |
-
|
| |
- The first time that you use Arcanist, it will ask for an API key which can be
|
| |
- retrieved from a link contained in that prompt.
|
| |
-
|
| |
- Arcanist will create a new code review on our Phabricator instance and prompt
|
| |
- you for information about the testing which has been done, a description of the
|
| |
- code under review and people to whom the review should be assigned. If you're
|
| |
- not clear on who should review your code, leave the ``reviewers`` section blank
|
| |
- and someone will either review your code or assign the review task to someone
|
| |
- who will.
|
| |
+ Make sure to run all unit and functional tests before submitting code for
|
| |
+ review. Any code that causes test failure will receive requests to fix the
|
| |
+ offending code or will be rejected. See :ref:`running-tests` for information
|
| |
+ on running unit and functional tests.
|
| |
|
| |
|
| |
Updating code reviews
|
| |
@@ -199,13 +121,6 @@
|
| |
the requested changes have been made in your feature branch, commit them and
|
| |
make sure that your branch is still up to date with respect to ``origin/develop``.
|
| |
|
| |
- To update the existing review, use::
|
| |
-
|
| |
- arc diff develop --update DXXX
|
| |
-
|
| |
- Where ``DXXX`` is the Differential ID assigned to your review when it was
|
| |
- originally created.
|
| |
-
|
| |
|
| |
Pushing code
|
| |
^^^^^^^^^^^^
|
| |
@@ -226,46 +141,27 @@
|
| |
before starting the merge process, else messy commits and merges may ensue.
|
| |
Once ``develop`` is up-to-date, the basic workflow to use is::
|
| |
|
| |
- git checkout feature/TXXX-some-feature
|
| |
+ git checkout feature/XXX-some-feature
|
| |
git rebase develop
|
| |
|
| |
To merge the code into develop, use one of two commands. If the feature can be
|
| |
reasonably expressed in one commit (most features), use::
|
| |
|
| |
- git flow feature finish --squash TXXX-some-feature
|
| |
+ git flow feature finish --squash XXX-some-feature
|
| |
|
| |
Else, if the Feature is larger and should cover multiple commits (less common),
|
| |
use::
|
| |
|
| |
- git flow feature finish TXXX-some-feature
|
| |
+ git flow feature finish XXX-some-feature
|
| |
|
| |
- After merging the code, please inspect log messages in case they need to be
|
| |
- shortened (Phabricator likes to make long commit messages). Groups of commits
|
| |
- should at least have a short description of their content and a link to the
|
| |
- revision in differential. Once the feature is ready, push to origin::
|
| |
+ After merging the code, please inspect git commit description and make it
|
| |
+ prettier if needed. Groups of commits should at least have a short description
|
| |
+ of their content and a link to the issue in Pagure. Once the feature is ready,
|
| |
+ push to origin::
|
| |
|
| |
git push origin develop
|
| |
|
| |
|
| |
-
|
| |
- Reviewing code
|
| |
- --------------
|
| |
-
|
| |
- To review code, use `Phabricator's web interface <https://phab.qa.fedoraproject.org/>`_
|
| |
- to submit comments, request changes or accept reviews.
|
| |
-
|
| |
- If you want to look at the code under review locally to run tests or test
|
| |
- suggestions prior to posting them, use Arcanist to apply the review code.
|
| |
-
|
| |
- Make sure that your local repo is at the same base revision as the code under
|
| |
- review (usually origin/develop) and run the following command::
|
| |
-
|
| |
- arc patch DXXX
|
| |
-
|
| |
- Where ``DXXX`` is the review id that you're interested in. Arcanist will grab the
|
| |
- code under review and apply it to a local branch named ``arcpatch-DXXX``. You can
|
| |
- then look at the code locally or make modifications.
|
| |
-
|
| |
Writing directives
|
| |
==================
|
| |
|
| |
@@ -308,11 +204,9 @@
|
| |
Sphinx has several built-in info fields which should be used to document
|
| |
function/method arguments and return data.
|
| |
|
| |
-
|
| |
The following is an excerpt from `the Sphinx documentation
|
| |
<http://sphinx-doc.org/domains.html#info-field-lists>`_
|
| |
|
| |
-
|
| |
Inside Python object description directives, reST field lists with these fields
|
| |
are recognized and formatted nicely:
|
| |
|
| |
Yes, we will probably need this variable in the future. However I would choose different name, probably 'taskotron_item_type', since 'item' is already taken by ansible.