From 076cdfd58522619c0eba1eb56304a71b7f527433 Mon Sep 17 00:00:00 2001 From: Pablo Hoffman Date: Mon, 17 May 2010 20:10:46 -0300 Subject: [PATCH] Added documentation about contributing to Scrapy --- docs/contributing.rst | 154 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 4 ++ 2 files changed, 158 insertions(+) create mode 100644 docs/contributing.rst diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..cbe6c67e9 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,154 @@ +====================== +Contributing to Scrapy +====================== + +There are many ways to contribute to Scrapy. Here are some of them: + +* Blog about Scrapy. Tell the world how you're using Scrapy. This will help + newcomers with more examples and the Scrapy project to increase its + visibility. + +* Report bugs and request features in our `ticket tracker`_, trying to follow + the guidelines detailed in `Reporting bugs`_ below. + +* Submit patches for new functionality and/or bug fixes. Please read + `Submitting patches`_ below for details on how to submit a patch. + +* Join the `scrapy-developers`_ mailing list and share your ideas on how to + improve Scrapy. We're always open to suggestions. + +Reporting bugs +============== + +Well-written bug report are very helpful, so keep in mind the following +guidelines when reporting a new bug. + +* check the :ref:`FAQ ` first to see if your issue is addressed in a + well-known question + +* `search the issue tracker` to see if your issues has already been reported. + If it has, don't dismiss the report but check the ticket history and + comments, you may have additional useful information to contribute. + +* search the `scrapy-users` list to see if it has been discussed there, or + if you're not sure if what you're seeing is a bug. You can also ask in the + `#scrapy` IRC channel. + +* write complete, reproducible, specific bug reports. The smaller the test + case, the better. Remember that other developers won't have your project to + reproduce the bug, so please include all relevant files required to reproduce + it. + +Submitting patches +================== + +The better written a patch is, the higher chance that it'll get accepted and +the sooner that will be merged. + +Well-written patches should: + +* contain the minimum amount of code required for the specific change. Small + patches are easier to review and merge. So, if you're doing more than one + change (or bug fix), please consider submitting one patch per change. Do not + collapse multiple changes into a single patch. For big changes consider using + a patch queue. + +* pass all unit-tests. See `Running tests` below. + +* include one (or more) test cases that check the bug fixed or the new + functionality added. See `Writing tests`_ below. + +* if you're adding or changing a public (documented) API, please include + the proper update to the documentation. See `Documentation policies`_ below. + +To submit patches, you can follow any of these mechanisms: + +* create appropriate tickets in the issue tracker and attach the patches to + those tickets. The patches can be generated using ``hg diff``. + +* send the patches to the `scrapy-developers` list, along with a comment + explaining what was fixed or the new functionality (what it is, why it's + needed, etc). The more info you include, the easier will be for core + developers to understand and accept your patch. + +* fork the `Github mirror`_ and send a pull request when you're done working on + the patch + +* clone the `Bitbucket mirror`_ and send a pull request when you're done + working on the patch + +You can also discuss the new functionality (or bug fix) in `scrapy-developers` +first, before creating the patch, but it's always good to have a patch ready to +illustrate your arguments and show that you have put some additional thought +into the subject. + +Coding style +============ + +Please follow these coding conventions when writing code for inclusion in +Scrapy: + +* Unless otherwise specified, follow :pep:`8`. + +* It's OK to use lines longer than 80 chars if it improves the code + readability. + +* Please don't put your name in the code you contribute. Our policy is to keep + contributor's name in ``AUTHORS`` file distributed with Scrapy. + +Documentation policies +====================== + +* **Don't** use docstrings for documenting classes, or methods which are + already documented in the official (sphinx) documentation. For example, the + :meth:`ItemLoader.add_value` method should be documented in the sphinx + documentation and not its docstring. + +* **Do** use docstrings for documenting functions not present in the official + (sphinx) documentation, such as functions from ``scrapy.utils`` package and + sub-modules. + +Tests +===== + +Tests are implemented using the `Twisted unit-testing framework` called +``trial``. + +Running tests +------------- + +To run all tests go to the root directory of Scrapy source code and run: + + ``bin/runtests.sh`` (on unix) + + ``bin/runtests.bat`` (on windows) + +To run a specific test (say ``scrapy.tests.test_contrib_loader``) use: + + ``bin/runtests.sh scrapy.tests.test_contrib_loader`` (on unix) + + ``bin/runtests.bat scrapy.tests.test_contrib_loader`` (on windows) + +Writing tests +------------- + +All functionality (including new features and bug fixes) must include a test +case to check it, so please include tests for your patches if you want them to +get accepted sooner. + +Scrapy uses unit-tests, which are located in the ``scrapy.tests`` package +(``scrapy/tests`` directory). Their module name typically resembles the full +path of the module they're testing. For example, the item loaders code is in:: + + scrapy.contrib.loader + +And their unit-tests are in:: + + scrapy.tests.test_contrib_loader + +.. _ticket tracker: http://dev.scrapy.org/newticket +.. _scrapy-users: http://groups.google.com/group/scrapy-users +.. _scrapy-developers: http://groups.google.com/group/scrapy-developers +.. _Github mirror: http://github.com/insophia/scrapy/ +.. _Bitbucket mirror: http://bitbucket.org/insophia/scrapy/ +.. _Twisted unit-testing framework: http://twistedmatrix.com/documents/current/core/development/policy/test-standard.html diff --git a/docs/index.rst b/docs/index.rst index 471a5983d..0258271a1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -197,9 +197,13 @@ All the rest .. toctree:: :hidden: + contributing api-stability experimental/index +:doc:`contributing` + Learn how to contribute to the Scrapy project. + :doc:`api-stability` Understand Scrapy versioning and API stability.