Taskotron contribution guide: Difference between revisions

Latest revision as of 14:44, 7 May 2020

Taskotron development reached end of life
Taskotron has been sunset in Fedora Infrastructure. It is no longer running and no longer being developed. You can use these wiki pages to learn about its history, but please be aware that the information is no longer actual.

Repositories

The repositories for the various components of Taskotron can be found on Pagure:

https://pagure.io/group/taskotron

The repositories for the tasks developed alongside Taskotron itself are prefixed with task-.

Feel free to submit bugs or pull requests for any of these repositories. Pull requests in Pagure work much as they do in github, which you may well be familiar with: you can use the web interface to 'fork' the main project into your user namespace, then push changes to your fork (it's best to use one git branch per change) and use the web interface to submit pull requests from branches in your fork.

Getting help

Remember, if you want to help out but are having trouble following these instructions, you can always get in touch with us for help! Please mail qa-devel or ask in #fedora-qa^[?] and someone will likely be able to help you out.

Taskotron-specific instructions

There are some specific considerations for contributing to Taskotron components.

virtualenv

For most Taskotron components, we recommend you submit diffs from within a virtualenv. This will ensure the tests and linter (see below) run correctly. If run directly from the host system, they may not do so. The general process for creating and entering a virtualenv is as follows:

dnf install python2-virtualenv python-pip
virtualenv --system-site-packages env_somename/
source env_somename/bin/activate

env_somename is an arbitrary name for the virtualenv; it's customary to name it for the project, but you can call it anything. To exit the virtualenv, run deactivate. Usually, after entering the environment, this will install the requirements for testing (and, if appropriate, running a development instance of) the project, and install the project within the virtualenv in 'editable' mode so that changes you make to the source will be immediately reflected when running the code in the virtualenv:

pip install --ignore-installed -r requirements.txt
pip install -e .

Each project's own README file should usually contain more detailed instructions on this step for the specific project, so check that out too.

gitflow

Gitflow is a git branching strategy that has been used successfully in the blocker tracking app and several Fedora infra apps. Most Taskotron component projects use the gitflow strategy.

Run

# fork the project and clone it
git checkout develop
git pull
git checkout -b feature/fixurl
# do your work
git commit
git push
# submit a pull request from web UI

Always remember to do a git pull to get all the latest changes.

Use the develop branch
When using gitflow, the current in-development branch is develop, not master. This means you should always branch off develop when developing changes.

Tests and linting

Taskotron components usually have test suites built on Pytest, and run lint checks using flake8. To ensure you have these packages installed, run sudo dnf install pytest python2-flake8 python-pep8. When testing and submitting changes, remember to run pytest inside your virtualenv to ensure the tests run correctly. Run flake8 and pep8 on files you modified to check for other errors (TODO: add better instructions).

General Thoughts and conventions

Be smart
All code going into develop branches MUST be reviewed
All code should have good unit tests where appropriate
When in doubt, ask

@@ Line 1: / Line 1: @@
-This is an initial guide to getting started with contributing to taskotron, please let us know if you find any errors in this document or if something doesn't make sense
+{{admon/caution|Taskotron development reached end of life|[[Taskotron]] has been sunset in Fedora Infrastructure. It is no longer running and no longer being developed. You can use these wiki pages to learn about its history, but please be aware that the information is no longer actual.}}
-= Introduction =
+== Repositories ==
-= Getting the Code =
+The repositories for the various components of [[Taskotron]] can be found on [https://pagure.io Pagure]:
-For now, all taskotron related code is on bitbucket. You can find most of the needed repositories under the [https://bitbucket.org/fedoraqa fedoraqa team].
-* [https://bitbucket.org/fedoraqa/libtaskotron libtaskotron]
+''' https://pagure.io/group/taskotron '''
-* [https://bitbucket.org/fedoraqa/depcheck-mk-2 depcheck mk 2]
-* [https://bitbucket.org/fedoraqa/taskotron-trigger taskotron trigger]
-* [https://bitbucket.org/fedoraqa/task-rpmlint task-rpmlint]
-Other repos which are potentially of interest are:
+The repositories for the tasks developed alongside Taskotron itself are prefixed with ''task-''.
-* [https://bitbucket.org/rajcze/resultsdb resultsdb]
-* [https://bitbucket.org/rajcze/resultsdb_frontend resultsdb_frontend]
-* [https://bitbucket.org/rajcze/resultsdb_api resultsdb client]
-If you need team membership, send a message out to qa-devel@ or file a ticket in phabricator against the infrastructure project.
+Feel free to submit bugs or pull requests for any of these repositories. Pull requests in Pagure work much as they do in github, which you may well be familiar with: you can use the web interface to 'fork' the main project into your user namespace, then push changes to your fork (it's best to use one git branch per change) and use the web interface to submit pull requests from branches in your fork.
-= Getting the Tools =
+== Getting help ==
-A general list of the tools we are using (read: should be installed on dev machines) and available in the Fedora repos are:
+Remember, if you want to help out but are having trouble following these instructions, you can always get in touch with us for help! Please mail {{fplist|qa-devel}} or ask in {{fpchat|#fedora-qa}} and someone will likely be able to help you out.
-* git
-* py.test
-* gitflow
+== Taskotron-specific instructions ==
-== gitflow ==
+There are some specific considerations for contributing to Taskotron components.
-Gitflow is a git branching strategy that has been used successfully in the blocker tracking app and several Fedora infra apps.
+=== virtualenv ===
-* [http://nvie.com/posts/a-successful-git-branching-model/ Description of the gitflow strategy]
+For most Taskotron components, we recommend you submit diffs from within a [http://docs.python-guide.org/en/latest/dev/virtualenvs/ virtualenv]. This will ensure the tests and linter (see below) run correctly. If run directly from the host system, they may not do so. The general process for creating and entering a virtualenv is as follows:
-* [https://github.com/nvie/gitflow gitflow tool code and docs]
+ dnf install python2-virtualenv python-pip
+ virtualenv --system-site-packages env_somename/
+ source env_somename/bin/activate
-{{admon/note|Use the develop branch|When using gitflow, the current in-development branch is <code>develop</code>, not <code>master</code>. Be careful not to start developing against an older branch}}
+{{code|env_somename}} is an arbitrary name for the virtualenv; it's customary to name it for the project, but you can call it anything. To exit the virtualenv, run {{code|deactivate}}. Usually, after entering the environment, this will install the requirements for testing (and, if appropriate, running a development instance of) the project, and install the project within the virtualenv in 'editable' mode so that changes you make to the source will be immediately reflected when running the code in the virtualenv:
-== Arcanist ==
+ pip install --ignore-installed -r requirements.txt
-At the time of this writing, the only way to submit code reviews is to use phabricator's cli tool, [http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide.html arcanist].
+ pip install -e .
-=== Installing Arcanist ===
+Each project's own README file should usually contain more detailed instructions on this step for the specific project, so check that out too.
-{{admon/important|Use the Provided Packages|Do not install arcanist using the upstream installation guide. This will install whatever code is in git and may not match the phabricator server we are using.}}
-There are phabricator related packages available for Fedora in a siderepo and you'll need to enable this siderepo before installing arcanist:
+=== gitflow ===
-<pre>
+Gitflow is a git branching strategy that has been used successfully in the blocker tracking app and several Fedora infra apps. Most Taskotron component projects use the gitflow strategy.
-sudo curl http://repos.fedorapeople.org/repos/tflink/phabricator/fedora-phabricator.repo -o /etc/yum.repos.d/fedora-phabricator.repo
-</pre>
-After that, just run <code>yum install arcanist</code> to install arcanist.
+* [http://nvie.com/posts/a-successful-git-branching-model/ Description of the gitflow strategy]
+* [https://github.com/nvie/gitflow gitflow tool code and docs]
-=== Arcanist Setup ===
+Run
-In order to communicate with the phabricator instance, arcanist needs to have a certificate associated with your phabricator user. The easiest way to configure this is to clone the libtaskotron repo and from the checkout, execute <code>arc install-certificate</code>
+ # fork the project and clone it
+ git checkout develop
+ git pull
+ git checkout -b feature/fixurl
+ # do your work
+ git commit
+ git push
+ # submit a pull request from web UI
-You will be prompted to visit a link for a generated certificate used for api calls. After visiting that link and logging into phabricator, you will see a string of characters in a text box. Copy those characters and paste them into the arc prompt.
+Always remember to do a {{code|git pull}} to get all the latest changes.
-=== Submitting a Code Review ===
+{{admon/note|Use the develop branch|When using gitflow, the current in-development branch is {{code|develop}}, not {{code|master}}. This means you should always branch off {{code|develop}} when developing changes.}}
-In short, code reviews are submitted through arcanist to phabricator through the <code>arc diff</code> command. More detailed instructions are available in the [http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide_arc_diff.html arcanist user guide].
+=== Tests and linting ===
+Taskotron components usually have test suites built on [http://docs.pytest.org/en/latest/ Pytest], and run lint checks using [https://github.com/PyCQA/flake8 flake8]. To ensure you have these packages installed, run {{code|sudo dnf install pytest python2-flake8 python-pep8}}. When testing and submitting changes, remember to run {{code|pytest}} inside your virtualenv to ensure the tests run correctly. Run {{code|flake8}} and {{code|pep8}} on files you modified to check for other errors (TODO: add better instructions).
-= General Thoughts and Conventions =
+=== General Thoughts and conventions ===
-These will be fleshed out more in the near future but in general:
 * Be smart
-* All code going into develop branches **MUST** be reviewed
+* All code going into develop branches '''MUST''' be reviewed
 * All code should have good unit tests where appropriate
-** When in doubt, ask
+* When in doubt, ask
+[[Category:Taskotron]]

Search