development.rst 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323
  1. Development
  2. ===========
  3. Get the sources
  4. ---------------
  5. Anonymous:
  6. ::
  7. git clone https://pagure.io/pagure.git
  8. Contributors:
  9. ::
  10. git clone ssh://git@pagure.io/pagure.git
  11. Dependencies
  12. ------------
  13. Install the build dependencies of pagure:
  14. ::
  15. sudo dnf install git python-virtualenv libgit2-devel \
  16. libjpeg-devel gcc libffi-devel redhat-rpm-config
  17. The python dependencies of pagure are listed in the file ``requirements.txt``
  18. at the top level of the sources.
  19. ::
  20. virtualenv pagure_env
  21. source ./pagure_env/bin/activate
  22. pip install pygit2==<version of libgit2 found>.* # e.g. 0.23.*
  23. pip install -r requirements.txt
  24. .. note:: working in a `virtualenv <http://www.virtualenv.org/en/latest/>`_
  25. is tricky due to the dependency on `pygit2 <http://www.pygit2.org/>`_
  26. and thus on `libgit2 <https://libgit2.github.com/>`_
  27. but the pygit2 `documentation has a solution for this
  28. <http://www.pygit2.org/install.html#libgit2-within-a-virtual-environment>`_.
  29. How to run pagure
  30. -----------------
  31. There are several options when it comes to a development environment. Vagrant
  32. will provide you with a virtual machine which you can develop on, you can use
  33. a container to run pagure or you can install it directly on your host machine.
  34. The README has detailed instructions for the different options.
  35. Run pagure for development
  36. --------------------------
  37. Adjust the configuration file (secret key, database URL, admin group...)
  38. See :doc:`configuration` for more detailed information about the
  39. configuration.
  40. Create the database scheme::
  41. ./createdb.py
  42. Create the folder that will receive the different git repositories:
  43. ::
  44. mkdir {repos,docs,forks,tickets,requests,remotes}
  45. Run the server:
  46. ::
  47. ./runserver.py
  48. If you want to change some configuration key you can create a file, place
  49. the configuration change in it and use it with
  50. ::
  51. ./runserver.py -c <config_file>
  52. For example, create the file ``config`` with in it:
  53. ::
  54. from datetime import timedelta
  55. # Makes the admin session longer
  56. ADMIN_SESSION_LIFETIME = timedelta(minutes=20000000)
  57. # Use a postgresql database instead of sqlite
  58. DB_URL = 'postgresql://user:pass@localhost/pagure'
  59. # Change the OpenID endpoint
  60. FAS_OPENID_ENDPOINT = 'https://id.stg.fedoraproject.org'
  61. APP_URL = '*'
  62. EVENTSOURCE_SOURCE = 'http://localhost:8080'
  63. EVENTSOURCE_PORT = '8080'
  64. DOC_APP_URL = '*'
  65. # Avoid sending email when developing
  66. EMAIL_SEND = False
  67. and run the server with:
  68. ::
  69. ./runserver.py -c config
  70. To get some profiling information you can also run it as:
  71. ::
  72. ./runserver.py --profile
  73. You should be able to access the server at http://localhost:5000
  74. Every time you save a file, the project will be automatically restarted
  75. so you can see your change immediately.
  76. Create a pull-request for testing
  77. ----------------------------------
  78. When working on pagure, it is pretty often that one wanted to work on a
  79. feature or a bug related to pull-requests needs to create one.
  80. Making a pull-request for development purposes isn't hard, if you remember
  81. that since you're running a local instance, the git repos created in your
  82. pagure instance are also local.
  83. So here are in a few steps that one could perform to create a pull-request in a
  84. local pagure instance.
  85. * Create a project on your pagure instance, let's say it will be called ``test``
  86. * Create a folder ``clones`` somewhere in your system (you probably do not
  87. want it in the ``repos`` folder created above, next to it is fine though)::
  88. mkdir clones
  89. * Clone the repo of the ``test`` project into this ``clones`` folder and move into it::
  90. cd clones
  91. git clone ~/path/to/pagure/repos/test.git
  92. cd test
  93. * Add and commit some files::
  94. echo "*~" > .gitignore
  95. git add .gitignore
  96. git commit -m "Add a .gitignore file"
  97. echo "BSD" > LICENSE
  98. git add LICENSE
  99. git commit -m "Add a LICENSE file"
  100. * Push these changes::
  101. git push -u origin master
  102. * Create a new branch and add a commit in it::
  103. git branch new_branch
  104. git checkout new_branch
  105. touch test
  106. git add test
  107. git commit -m "Add file: test"
  108. * Push this new branch::
  109. git push -u origin new_branch
  110. Then go back to your pagure instance running in your web-browser, check the
  111. ``test`` project. You should see two branches: ``master`` and ``new_branch``.
  112. From there you should be able to open a new pull-request, either from the
  113. front page or via the ``File Pull Request`` button in the ``Pull Requests``
  114. page.
  115. Coding standards
  116. ----------------
  117. We are trying to make the code `PEP8-compliant
  118. <http://www.python.org/dev/peps/pep-0008/>`_. There is a `flake8 tool
  119. <http://pypi.python.org/pypi/flake8>`_ that can automatically check
  120. your source.
  121. We run the source code through `black <https://pypi.python.org/pypi/black>`_
  122. as part of the tests, so you may have to do some adjustments or run it
  123. yourself (which is simple: ``black /path/to/pagure``).
  124. .. note:: flake8 and black are available in Fedora:
  125. ::
  126. dnf install python3-flake8 python3-black
  127. or
  128. ::
  129. yum install python3-flake8 python3-black
  130. Send patch
  131. ----------
  132. The easiest way to work on pagure is to make your own branch in git, make
  133. your changes to this branch, commit whenever you want, rebase on master,
  134. whenever you need and when you are done, send the patch either by email,
  135. via the trac or a pull-request (using git or github).
  136. The workflow would therefore be something like:
  137. ::
  138. git branch <my_shiny_feature>
  139. git checkout <my_shiny_feature>
  140. <work>
  141. git commit file1 file2
  142. <more work>
  143. git commit file3 file4
  144. git checkout master
  145. git pull
  146. git checkout <my_shiny_feature>
  147. git rebase master
  148. git format-patch -2
  149. This will create two patch files that you can send by email to submit in a ticket
  150. on pagure, by email or after forking the project on pagure by submitting a
  151. pull-request (in which case the last step above ``git format-patch -2`` is not
  152. needed.
  153. .. note:: Though not required, it’s a good idea to begin the commit message
  154. with a single short (less than 50 character) line summarizing the
  155. change, followed by a blank line and then a more thorough description.
  156. The text up to the first blank line in a commit message is treated
  157. as the commit title, and that title is used throughout Git.
  158. For example, git-format-patch turns a commit into email, and it
  159. uses the title on the Subject line and the rest of the commit in
  160. the body.
  161. Pagure uses lines that contain only 'Fixes #number' as references
  162. to issues. If for example a commit message of a pagure patch has
  163. a line 'Fixes #3547' and a pullrequest (PR) gets created in pagure,
  164. this PR will be linked to from ``https://pagure.io/pagure/issue/3547``
  165. Unit-tests
  166. ----------
  167. Pagure has a number of unit-tests.
  168. We aim at having a full (100%) coverage of the whole code (including the
  169. Flask application) and of course a smart coverage as in we want to check
  170. that the functions work the way we want but also that they fail when we
  171. expect it and the way we expect it.
  172. Tests checking that function are failing when/how we want are as important
  173. as tests checking they work the way they are intended to.
  174. So here are a few steps that one could perform to run unit-tests in a
  175. local pagure instance.
  176. * Install the dependencies::
  177. pip install -r requirements-testing.txt
  178. * Run it::
  179. python runtests.py run
  180. You can also use::
  181. python runtests.py --help
  182. to see other options supported.
  183. Each unit-tests files (located under ``tests/``) can be called
  184. by alone, allowing easier debugging of the tests. For example:
  185. ::
  186. python runtests.py run tests/test_pagure_lib.py
  187. .. note:: In order to have coverage information you might have to install
  188. ``python-coverage``
  189. ::
  190. dnf install python-coverage
  191. or
  192. ::
  193. yum install python-coverage
  194. To run the unit-tests, there is also a container available with all the dependencies needed.
  195. Use the following command to run the tests ::
  196. $ ./dev/run-tests-container.py
  197. This command will build a fedora based container and execute the test suite. You can also
  198. limit the tests to unit-test files or single tests similar to the ``python runtests.py``
  199. options described above. You need set the environment variables REPO and BRANCH if the
  200. tests are not yet available in the upstream pagure master branch.