Story 1988 - Easier documentation for new developers

closes #1988
https://pulp.plan.io/issues/1988

dev-guide/contributing/branching.rst
* Explain Bug fix branches more in detail
* Explain Feature Branches more in detail
* Add Naming of the new Branch section
* Add note about multiple commits

dev-guide/contributing/bugs.rst
* Add how to proceed when fixing bug
* Add note how to view logs

dev-guide/contributing/dev_setup.rst
* Add note about libivrt and docker support
* Add note how to handle not removed virbr
* Fix example in Creating the Vagrant environment
* Add section Using Vagrant
* Fix renamed package qpid-cpp-server-store -> qpid-cpp-server-linearstore

dev-guide/policies/style.rst
* Add flake8 suggestion

dev-guide/policies/testing.rst
* Add note about coverage

user-guide/glossary.rst
* Add publish
* Add sync

docs/dev-guide/contributing/branching.rst

@@ -80,21 +80,29 @@ When a hotfix needs to be made, a branch will be created from the most recent
 fork to the hotfix branch), a new tag will be built from the tip of the hotfix
 branch, and the hotfix branch can be merged to ``x.y-dev``.
 
+.. _bug_fix_branches:
 
 Bug Fix Branches
 ----------------
 
 When creating a Pull Request (PR) that fixes a specific bug, title the PR as
-you would the :ref:`git commit message <commit_messages>`.
+you would a :ref:`git commit message <commit_messages>` with a short,
+human-readable description. Bug fixes should always be made against
+the latest available ``x.y-dev`` branch.
 
 
+.. _feature_branches:
+
 Feature Branches
 ----------------
 
-Similar to bug fix branches, when creating a pull request that holds features
-until they are merged into a development branch, the pull request branch should
-be a brief name relevant to the feature. For example, a branch to add persistent
-named searches might be named "feature/named-searches".
+Similar to bug fix branches, the name of a feature branch and its associated
+Pull Request should be a short, human-readable description of the feature being added.
+For example, a branch to add persistent named searches might be named
+``feature/named-searches``. Also new features should go into latest ``x.y-dev`` branch
+which does not have corresponding ``x.y-release`` branch. In case there is
+no such branch then the ``master`` branch is the right one. If you are not sure
+``master`` branch is always the correct one.
 
 
 .. _choosing-upstream-branch:
@@ -103,8 +111,21 @@ Choosing an Upstream Branch
 ---------------------------
 
 When creating a bug fix or feature branch, it is very important to choose the
-right upstream branch. The general rule is to always choose the oldest upstream
-branch that will need to contain your work.
+right upstream branch. The general rule is to always choose the oldest supported upstream
+branch that will need to contain your work. For more info see above
+:ref:`Feature Branches <feature_branches>` or :ref:`Bug Fix Branches <bug_fix_branches>`.
+
+
+.. _naming-of-the-new-branch:
+
+Naming of the new Branch
+------------------------
+
+It is advised to use the number of your issue or story when you are creating your new branch name.
+Some examples of naming:
+
+  * Issue #2524 - Vagrant enviroment is not starting properly => ``2524-vagrant-init-fix``
+  * Story #2523 - Implement regex upload of packages => ``2523-regex-upload``
 
 .. _commit_messages:
 
@@ -148,6 +169,10 @@ Putting this altogether, the following is an example of a good commit message::
     closes #1392
     https://pulp.plan.io/issues/1392
 
+.. note::
+  In case you have multiple commits use ``re`` or ``ref`` in all of them and ``fixes`` or ``close``
+  only in the last one to avoid closing the issue before it's completely done.
+
 Cherry-picking and Rebasing
 ---------------------------
 

docs/dev-guide/contributing/bugs.rst

@@ -80,6 +80,30 @@ Fixing
 
 When fixing a bug, all bugs will follow this process, regardless of how trivial.
 
+First of all you need to reproduce this bug. If this error is connected with client try to use
+``-vv`` flag to obtain complete information. It can also be useful to look into server log.
+If there is a traceback, try to look there first and individualy look for the bug. In some cases
+you can try to reproduce the error in the python console. Be aware of the fact that bug can not only
+be caused by just the plugin or just the platform, it could also be caused by the interaction
+of faults present in both components. Always fix any unittests broken by a change, and add
+new test code to cover code additions. Before you commit manualy test if bug is fixed after
+that you should run all unittests via ``run-tests.py`` to check whether something got
+broken by your fix. If tests pass you are good to push and submit PR by rules mentioned below.
+
+.. note::
+  In systems that use systemd such as RHEL 7 (and later) and Fedora 15 (and later) you can use
+  ::
+
+      journalctl -u goferd.service \
+                 -u httpd.service \
+                 -u pulp_workers.service \
+                 -u pulp_celerybeat.service \
+                 -u pulp_resource_manager.service \
+                 -u pulp_streamer.service
+
+  also you can add ``--boot`` switch to view logs only from the current boot of the system. On other
+  systems take a look into ``/var/log/messages``.
+
 Developer
 ^^^^^^^^^
 

docs/dev-guide/contributing/dev_setup.rst

@@ -35,24 +35,28 @@ Reasons to prefer docker:
 * improved performance
 * host may freely access processes within the guest (e.g. for debugging)
 
+.. note::
+  ``libvirt`` is the only officially supported and tested provider and will work in all cases.
+  ``docker`` provider is available, but might not be fully functional.
+
 Prerequisites for libvirt
 -------------------------
 
 Follow these steps:
 
 #. Install vagrant, ansible, and nfs-utils. NFS will be used to share your code directory with the
    deployed virtual machine::
-   
+
       $ sudo dnf install ansible nfs-utils vagrant-libvirt
 
 #. You will need to grant the nfsnobody user rx access to the folder that you check out your code
    under. Many developers check out code into $HOME/devel or similar. In Fedora, $HOME typically
    does not allow such access to other users. If your code is in $HOME, you will need to::
-   
+
       $ setfacl -m user:nfsnobody:r-x $HOME  # Season to taste, as per above
 
    .. warning::
-   
+
       Wherever you have hosted your code, it would be good to verify that nfsnobody is able to read
       it. If you experience an error message similar to
       "mount.nfs: access denied by server while mounting 192.168.121.1:/path/to/my/code/dir"
@@ -64,19 +68,25 @@ Follow these steps:
       $ sudo systemctl enable nfs-server && sudo systemctl start nfs-server
 
 #. You will need to allow NFS services through your firewall::
-   
+
       $ sudo firewall-cmd --permanent --add-service=nfs
       $ sudo firewall-cmd --permanent --add-service=rpc-bind
       $ sudo firewall-cmd --permanent --add-service=mountd
       $ sudo firewall-cmd --reload
 
+.. note::
+
+  If Vagrant will not start due to the error message
+  ``error creating bridge interface virbr0: File exists``, you can solve it by using
+  ``ifconfig virbr0 down`` and ``brctl delbr virbr``
+
 Prerequisites for docker
 ------------------------
 
 Follow these steps:
 
 #. Install vagrant, ansible, and docker::
-   
+
       $ sudo dnf install vagrant ansible docker
 
 #. Enable and start the docker service::
@@ -117,7 +127,7 @@ After preparing either the libvirt or docker prerequisites using the instruction
    Vagrant environment. We will finish by running ``vagrant reload``. This allows the machine to
    reboot after provisioning.::
 
-      $ cd pulp
+      $ cd devel
       $ cp Vagrantfile.example Vagrantfile
       # Choose ONE of the following, for your preferred provider:
       $ vagrant up --provider=libvirt
@@ -146,6 +156,26 @@ pulp_python, and so forth. Any plugins in folders that start with ``pulp_`` that
 in your host machine's code folder alongside the Pulp platform repository should have been installed
 and configured for virtualenv.
 
+Using Vagrant
+-------------
+
+The Vagrant environment provides some useful built-in commands by default.
+More information about them can be found in command ``phelp``.
+
+List of most useful commands:
+
+* ``pstart`` - Starts all pulp related servicies
+* ``ppopulate`` - Load default testing repositories
+
+.. note::
+
+    You have to issue ``pstart`` after starting vagrant.
+
+.. note::
+
+    If Vagrant is stopped incorrectly, mongo may not be able to start.
+    This can be solved by removing the file ``/var/lib/mongodb/mongod.lock``.
+    To avoid this, always stop your Vagrant environment with ``vagrant halt``.
 
 Advanced Vagrant
 ^^^^^^^^^^^^^^^^
@@ -337,9 +367,9 @@ pulls in the latest dependencies according to the spec file.
    out code. ``$ sudo yum remove pulp-\* python-pulp\*``
 
 #. Install some additional dependencies for development::
-   
+
         $ sudo yum install python-setuptools redhat-lsb mongodb mongodb-server \
-        qpid-cpp-server qpid-cpp-server-store python-qpid-qmf python-nose \
+        qpid-cpp-server qpid-cpp-server-linearstore python-qpid-qmf python-nose \
         python-mock python-paste python-pip python-flake8
 
 The only caveat to this approach is that these dependencies will need to be maintained after this
@@ -474,4 +504,3 @@ into the local source directory. It is run using the ``-U`` flag:
 Each python package installed above must be removed by its package name.::
 
   $ sudo pip uninstall <package name>
-

docs/dev-guide/contributing/documenting.rst

@@ -96,11 +96,11 @@ Which creates this link: :fixedbugs:`these great bugs were fixed <2.6.0>`
 Build Docs Locally
 ------------------
 
-Building docs locally is easy::
+Building docs locally is easy:
 
-    1. Navigate to the Sphinx project folder
-    2. ``make html``
-    3. Browse the docs the folder ``docs/_build/html``.
+1. Navigate to the Sphinx project folder
+2. ``make html``
+3. Browse the docs the folder ``docs/_build/html``.
 
 The Vagrant environment comes pre-loaded with all the dependencies you need
 to build the docs.
@@ -123,4 +123,4 @@ e-mail is sent to the docs maintainers who are expected to resolve issues.
 GA, RC, and Beta docs are triggered manually as part of the release process.
 
 See all of the `Jenkins doc builders <https://pulp-jenkins.rhev-ci-vms.eng.
-rdu2.redhat.com/view/Docs%20Builders/>`_.
+rdu2.redhat.com/view/Docs%20Builders/>`_.

docs/dev-guide/contributing/index.rst

@@ -19,10 +19,10 @@ For New Contributors
 
 If you are interested in contributing to Pulp, the best way is to select a bug
 that interests you and submit a patch for it. We use `Redmine
-<https://pulp.plan.io/projects/pulp/issues/new>`_
+<https://pulp.plan.io/projects/pulp/issues>`_
 for tracking bugs. Of course, you may have your own idea for a feature or
 bugfix as well! You may want to send an email to pulp-list@redhat.com or ask in
-the #pulp channel on freenode before working on your feature or bugfix. The
+the #pulp-dev channel on freenode before working on your feature or bugfix. The
 other contributors will be able to give you pointers and advice on how to
 proceed. Additionally, if you are looking for a bug that is suitable for a
 first-time contributor, feel free to ask.
@@ -41,31 +41,35 @@ available on the `GitHub help page <https://help.github.com/>`_.
 Contribution Checklist
 ^^^^^^^^^^^^^^^^^^^^^^
 
-1. Make sure that you choose the appropriate upstream branch.
+#. Make sure that you choose the appropriate upstream branch.
 
    :doc:`Branching <branching>`
 
-2. Test your code. We ask that all new code has 100% coverage.
+#. Test your code. We ask that all new code has 100% coverage.
 
    :doc:`Testing </dev-guide/policies/testing>`
 
-3. Please ensure that your code follows our style guide.
+#. Please ensure that your code follows our style guide.
 
    :doc:`Style Guide </dev-guide/policies/style>`
 
-4. Please make sure that any new features are documented and that changes are
+#. Please make sure that any new features are documented and that changes are
    reflected in existing docs.
 
    :doc:`Documentation <documenting>`
 
-5. Please squash your commits and use our commit message guidelines.
+#. Please squash your commits and use our commit message guidelines.
 
    :ref:`rebasing-and-squashing`
 
-6. Make sure your name is in our AUTHORS file found at the root of each of our
+#. Make sure your name is in our AUTHORS file found at the root of each of our
    repositories. That way you can prove to all your friends that you
    contributed to Pulp!
 
+#. Make a PR!
+
+    :ref:`Pull Requests <pull-requests>`
+
 Developer Guide
 ^^^^^^^^^^^^^^^
 .. toctree::

docs/dev-guide/contributing/merging.rst

@@ -1,6 +1,8 @@
 Merging
 =======
 
+.. _pull-requests:
+
 Pull Requests
 -------------
 

docs/dev-guide/glossary.rst

@@ -7,9 +7,9 @@ Glossary
 
   applicability data
     Applicability data for a consumer consists of arrays of applicable :term:`content unit` ids,
-    keyed by a content unit type. The definition of applicability itself defers for each content type. 
-    For example, in case of an rpm, a content unit is considered applicable to a consumer 
-    when an older version of the content unit installed on that consumer can be updated 
+    keyed by a content unit type. The definition of applicability itself differs for each content
+    type. For example, in case of an rpm, a content unit is considered applicable to a consumer
+    when an older version of the content unit installed on that consumer can be updated
     to the given content unit.
 
   binding

docs/dev-guide/policies/style.rst

@@ -7,6 +7,15 @@ PEP-8
 New Pulp code should adhere as closely as is reasonable to PEP-8. One modification is that our line
 length limit is 100 characters, which we chose to prevent line wrapping on GitHub.
 
+It is **recommended** to enable `flake8 <http://flake8.readthedocs.io/>`_ in your text editor.
+
+You should also place ``setup.cfg`` file in top directory with all pulp content,
+which will look like this::
+
+  [flake8]
+  ignore = D203
+  max-line-length = 100
+
 
 In-code Documentation
 ---------------------

docs/dev-guide/policies/testing.rst

@@ -79,3 +79,7 @@ The python ``coverage`` library is used to produce the reports and must be
 installed before running that script. An HTML version of the coverage report
 is created in the git repository root under ``coverage/index.html``.
 
+.. note::
+
+    If you want to see coverage report with lines which were not covered use
+    ``coverage report -m --omit="*/test/*"`` after running ``run-tests.py`` script.

docs/user-guide/glossary.rst

@@ -10,7 +10,7 @@ Glossary
     & control API which is used by the Pulp server to initiate content changes
     on the consumer.  It also sends scheduled reports concerning consumer
     status and installed content profiles to the Pulp server.
-    
+
   binding
     An association between a :term:`consumer` and a :term:`repository`
     :term:`distributor` for the purpose of installing :term:`content units <content unit>`
@@ -29,12 +29,12 @@ Glossary
     A managed system that is the consumer of content.  Consumption refers
     to the installation of software contained within a :term:`repository` and
     published by an associated :term:`distributor`.
-    
+
   content unit
     An individual piece of content managed by the Pulp server. A unit does not
     necessarily correspond to a file. It is possible that a content unit is
     defined as the aggregation of other content units as a grouping mechanism.
-    
+
   distributor
     Server-side plugin that takes content from a repository and publishes it
     for consumption. The process by which a distributor publishes content varies
@@ -86,6 +86,9 @@ Glossary
     to another Pulp server. Parent nodes provide content to child nodes. Child
     nodes consume content from a parent node as registered :term:`consumers <consumer>`.
 
+  publish
+    Make content available to users.
+
   registration
     The association of a :term:`consumer` to a Pulp server.  Once registered,
     a consumer is added to Pulp's inventory and may be :term:`bound <binding>` to
@@ -99,6 +102,10 @@ Glossary
     :term:`distributors <distributor>` associated which are used to publish
     its content to multiple destinations, formats, or protocols.
 
+    sync
+      Fetch metadata about content into pulp, can also download the
+      actual content.
+
   unit profile
     A list of :term:`content unit` installed on a :term:`consumer`.  The
     structure and content of each item in the profile varies based on the