Permalink
Browse files

Workflow docs.

  • Loading branch information...
1 parent 9ee736c commit 41d9753b360219a0b8b0506b4b306bc37918447f @ralphbean committed Sep 25, 2012
Showing with 123 additions and 47 deletions.
  1. +1 −0 CONTRIBUTING.rst
  2. +0 −47 README.rst
  3. +10 −0 doc/contributing.rst
  4. +11 −0 doc/deployment.rst
  5. +97 −0 doc/development.rst
  6. +4 −0 doc/index.rst
View
View
@@ -24,50 +24,3 @@ Build Status
+----------+-----------+
| develop | |develop| |
+----------+-----------+
-
-
-Hacking
--------
-
-Install the dependencies. (This list is a work in progress.
-The ``python-*`` packages from http://pypi.python.org/ are not listed
-for now, since they are ever-evolving.)::
-
- $ sudo yum install python-virtualenv openssl-devel zeromq-devel gcc
-
-Get the source::
-
- $ git clone git://github.com/ralphbean/fedmsg.git
- $ cd fedmsg
-
-Make a virtualenv::
-
- $ virtualenv fedmsg-env
- $ source fedmsg-env/bin/activate
- (fedmsg-env)$
-
-Pull down pypi dependencies::
-
- (fedmsg-env)$ python setup.py develop
-
-Try out the shell commands
---------------------------
-
-Having set up your environment in the `Hacking` section above, open up three
-terminals. In each of them, activate your virtualenv with::
-
- $ source fedmsg-env/bin/activate
-
-and in one, type::
-
- (fedmsg-env)$ fedmsg-relay
-
-In the second, type::
-
- (fedmsg-env)$ fedmsg-tail --pretty
-
-In the third, type::
-
- (fedmsg-env)$ echo "Hello, world" | fedmsg-logger
-
-And you should see the message appear in the ``fedmsg-tail`` term.
View
@@ -0,0 +1,10 @@
+Contributing
+============
+
+If you're submitting patches to fedmsg, please observe the following:
+
+ - Check that your python code is `PEP8-compliant
+ <http://www.python.org/dev/peps/pep-0008/>`_.
+ - Check that your code doesn't break the test suite. Instructions for running
+ the test suite can be found in :doc:`development`.
+ - If you are adding new code, please write tests for them in ``fedmsg/tests``.
View
@@ -0,0 +1,11 @@
+==========
+Deployment
+==========
+
+This document isn't yet written. If you have questions about deployment, please
+come and ask in ``#fedora-apps`` on freenode or on the `mailing list
+<https://admin.fedoraproject.org/mailman/listinfo/messaging-sig>`_.
+
+We have fedmsg successfully deployed (and growing) in `Fedora Infrastructure
+<https://fedorahosted.org/fedora-infrastructure/>`_. The code should be generic
+enough to run in other environments. If you come and ask, we'll write the docs.
View
@@ -0,0 +1,97 @@
+===========
+Development
+===========
+
+Using a virtualenv
+------------------
+
+Although you don't strictly *have* to, you should use
+`virtualenvwrapper <http://virtualenvwrapper.rtfd.org>`_ for isolating your
+development environment. It is to your benefit because you'll be able to
+install the latest fedmsg from a git checkout without messing with your system
+fedmsg install (if you have one). The instructions here will assume you are
+using that.
+
+You can install it with::
+
+ $ sudo yum install python-virtualenvwrapper
+
+.. note:: If you decide not to use python-virtualenvwrapper, you can always use
+ latest update of fedmsg in fedora. If you are doing this, simply ignore all
+ ``mkvirtualenv`` and ``workon`` commands in these instructions. You can
+ install fedmsg with ``sudo yum install fedmsg``.
+
+Development Dependencies
+------------------------
+
+Get::
+
+ $ sudo yum install python-virtualenv openssl-devel zeromq-devel gcc
+
+Cloning Upstream the Git Repo
+-----------------------------
+
+The source code is on github. For read-only access, simply::
+
+ $ git clone git://github.com/ralphbean/fedmsg.git
+
+Of course, you may want to do the usual `fork and then clone
+<https://help.github.com/articles/fork-a-repo>`_ pattern if you intend to
+submit patches/pull-requests (please do!).
+
+.. note:: If submitting patches, you should check :doc:`contributing` for
+ style guidelines.
+
+Setting up your virtualenv
+--------------------------
+
+Create a new, empty virtualenv and install all the dependencies from `pypi
+<http://pypi.python.org>`_::
+
+ $ cd fedmsg
+ $ mkvirtualenv fedmsg
+ (fedmsg)$ python setup.py develop
+
+You should also run the tests, just to make sure everything is sane::
+
+ (fedmsg)$ python setup.py test
+
+Try out the shell commands
+--------------------------
+
+Having set up your environment in the `Hacking` section above, open up three
+terminals. In each of them, activate your virtualenv with::
+
+ $ workon fedmsg
+
+and in one, type::
+
+ (fedmsg)$ fedmsg-relay
+
+In the second, type::
+
+ (fedmsg)$ fedmsg-tail --really-pretty
+
+In the third, type::
+
+ (fedmsg)$ echo "Hello, world" | fedmsg-logger
+
+And you should see the message appear in the ``fedmsg-tail`` term.
+
+Configuration
+-------------
+
+There is a folder in the root of the upstream git checkout named ``fedmsg.d/``.
+:module:`fedmsg.config` will try to read this whenever the fedmsg API is
+invoked. If you're starting a new project like a consumer or a webapp that is
+sending fedmsg messages, you'll need to copy the ``fedmsg.d/`` directory to the
+root directory of that project. In :doc:`deployment`, that folder is kept in
+``/etc/fedmsg.d/``.
+
+.. note:: Watch out: if you have a ``/etc/fedmsg.d/`` folder and a local
+ ``./fedmsg.d/``, fedmsg will read both. Global first, and then local.
+ Local values will overwrite system-wide ones.
+
+.. note:: The tutorial on `consuming FAS messages from stg
+ <http://threebean.org/blog/fedmsg-tutorial-consuming-fas-stg>`_ might be of
+ further help. It was created before these instructions were written.
View
@@ -12,6 +12,8 @@ See :doc:`overview` for a thorough introduction.
Publishing Messages with Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See :doc:`development` on setting up your environment and workflow.
+
.. code-block:: python
import fedmsg
@@ -73,6 +75,8 @@ Rough Outline of Stages of development/deployment
overview
topology
status
+ development
+ deployment
commands
publishing
consuming

0 comments on commit 41d9753

Please sign in to comment.