[ganeti/ganeti_webmgr] 84e644d Added header to process to clarify its purpose (2 commits)

[g...@osuosl.org]

The branch, enhancement/13785 has been updated

Old revision: 9d2ec0dd7de06cdfc4b34ff7db76e0ab9f12a5fc, new revision: 84e644dfd90312b5400d4d4a3c8b20c0b88f43cf.
via 84e644dfd90312b5400d4d4a3c8b20c0b88f43cf (commit)
via f7bbf6dcaf8de399b99ef4793c01a12301c00ddc (commit)
from 9d2ec0dd7de06cdfc4b34ff7db76e0ab9f12a5fc (commit)

- Log -----------------------------------------------------------------
commit 84e644dfd90312b5400d4d4a3c8b20c0b88f43cf
Author: Kennric <ken...@hypothetical.net>
Date: Mon Mar 31 10:34:12 2014 -0700

Added header to process to clarify its purpose

refs #13785

commit f7bbf6dcaf8de399b99ef4793c01a12301c00ddc
Author: Kennric <ken...@hypothetical.net>
Date: Mon Mar 31 10:05:50 2014 -0700

Misc cleanups per mathuin's input

refs #13785


Summary of changes:
docs/source/dev/developers.rst | 34 +++++++++++++--------
docs/source/dev/issues.rst | 55 ++++++++++++++++++++++------------
docs/source/dev/process.rst | 36 ++++++----------------
docs/source/index.rst | 3 +-
docs/source/{dev => ref}/search.rst | 0
5 files changed, 68 insertions(+), 60 deletions(-)
rename docs/source/{dev => ref}/search.rst (100%)

diff --git a/docs/source/dev/developers.rst b/docs/source/dev/developers.rst
index c948f30..9f83232 100644
--- a/docs/source/dev/developers.rst
+++ b/docs/source/dev/developers.rst
@@ -14,7 +14,7 @@ Issue Tracking

The bug tracker for |gwm| is at `code.osuosl.org`_, and all bugs and feature requests for |gwm| should be tracked there. Please create an issue for any code, documentation or translation you wish to contribute.

-Please see the :ref:`issues` for details on how to create informative issues.
+Please see :ref:`issues` for details on how to create informative issues.

.. _`code.osuosl.org`: https://code.osuosl.org/projects/ganeti-webmgr

@@ -28,7 +28,7 @@ From OSL's repository:

git clone git://git.osuosl.org/gitolite/ganeti/ganeti_webmgr

-Note that this is a read-only clone, commit access requires an account on our gitolite server. You must be `Submitting Code`_ and establish a relationship with us prior to being granted commit access.
+Note that this is a read-only clone, commit access requires an account on our gitolite server. Once you have established a relationship with us and submitted some code via email or pull requests, (see `Submitting Code`_) you can be considered for commit access to the master rpositiory.

When you have write access:

@@ -61,7 +61,7 @@ Git

If you are unfamiliar with Git, please read the `official Git tutorial`_ or `this excellent tutorial`_.

-There are many graphical Git UIs, if you are not comfortable working with Git on the command line. See `this list of Git GUI clients`_ for more information.
+There are many Git GUIs, if you are not comfortable working with Git on the command line. See `this list of Git GUI clients`_ for more information.

.. _`official Git tutorial`: http://git-scm.com/docs/gittutorial
.. _`this excellent tutorial`: http://www.vogella.com/articles/Git/article.html
@@ -108,7 +108,7 @@ Development VM
Test Cluster
~~~~~~~~~~~~

-For instructions on setting up and using a vagrant cluster to test your code, see :ref:`test_cluster`
+For instructions on setting up and using a vagrant cluster to test your code, see :ref:`test_cluster`.

Repository Layout
-----------------
@@ -116,12 +116,18 @@ Repository Layout
We loosely follow `Git-flow <http://github.com/nvie/gitflow>`_ for managing repository. Read about the `branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_ and why `you may wish to use it too <http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/>`_.


-- **master** - Releases only, this is the main public branch.
-- **release/<version>** - A release branch, the current release branch is tagged and merged into master.
-- **develop** - Mostly stable development branch. Small changes only. It is acceptable that this branch have bugs, but should remain mostly stable.
-- **feature/<issue number>** - New features, these will be merged into develop when complete.
-- **bug/<issue number>** - Bug fixes.
-- **enhancement/<issue number>** - Enhancements to existing features.
+**master**
+ Releases only, this is the main public branch.
+**release/<version>**
+ A release branch, the current release branch is tagged and merged into master.
+**develop**
+ Mostly stable development branch. Small changes only. It is acceptable that this branch have bugs, but should remain mostly stable.
+**feature/<issue number>**
+ New features, these will be merged into develop when complete.
+**bug/<issue number>**
+ Bug fixes.
+**enhancement/<issue number>**
+ Enhancements to existing features.

See :ref:`issues` for more information on issue types.

@@ -146,7 +152,7 @@ In addition to PEP 8:
Units
'''''

-Try to write modular code. Focus on isolating units of code that can be easily analyzed and tested. For sanity purposes, please try to avoid mutually recursive objects.
+Write modular code. Focus on isolating units of code that can be easily analyzed and tested. For sanity purposes, please avoid mutually recursive objects.

JSON
''''
@@ -206,7 +212,9 @@ Before working on a bug fix, determine if the faulty code is covered by a unit t
Writing Documentation
---------------------

-Documentation exists as RestructuredText files within the GWM repository, and as in-line comments in the source code itself.
+Documentation exists as `RestructuredText`_ files within the GWM repository, and as in-line comments in the source code itself.
+
+.. _`RestructuredText`: http://sphinx-doc.org/rest.html

Sphinx
''''''
@@ -215,7 +223,7 @@ The docs/ directory contains the full tree of documentation in RestructuredText

::

- pip install Sphinx
+ pip install -r requirements/docs.txt
cd docs
make html


diff --git a/docs/source/dev/issues.rst b/docs/source/dev/issues.rst
index de577d0..79869e2 100644
--- a/docs/source/dev/issues.rst
+++ b/docs/source/dev/issues.rst
@@ -1,13 +1,15 @@
.. _issues:

-Filing Issues
-=============
+Issues
+======

-Please follow this guide when filing new issues for Ganeti Web Manager
+Please follow this guide when filing new issues for Ganeti Web Manager.

Trackers
--------

+There are several "trackers" or categories of issues that can be filed.
+
Bugs
~~~~

@@ -17,38 +19,49 @@ don't work as expected.
Features
~~~~~~~~

-Features are full blown enhancements to the project that vastly improve
-the usability experience. They are generally referenced with a phrase
-like "The ability to..."
+Features are enhancements to the project that implement a new functionality.
+They are generally referenced with a phrase like "The ability to...".

Enhancements
~~~~~~~~~~~~

-Enhancements are minor updates to features. They are not errors
-encountered in features. They are an extension to a feature.
+Enhancements are updates to existing features. They are not errors
+encountered in features, but improve the functionality or usability of a feature.

Status
------

Status reflects where a ticket stands in the filing process.

-The available status' are:

-- New
-- In Progress
-- Won't Fix
-- Duplicate
-- Blocked
-- Feedback
-- Resolved
-- Upstream
-- Closed
-- Rejected
-- Can't Reproduce
+New
+ This issue is new and we haven't begun work on it, possibly haven't even decided whether we will work on it.
+In Progress
+ We are working on this issue.
+Won't Fix
+ This is a legitimate issue, but we've decided that it is not something we can or will work on
+Duplicate
+ This issue is actually a duplicate of an exisiting issue
+Blocked
+ We can't work on this issue until another issue is resolved
+Feedback
+ We've worked on this issue, or made some comments on it, and assigned it to someone for their feedback.
+Resolved
+ We've completed work on this issue.
+Upstream
+ This is actually an issue with some package or library we depend on.
+Closed
+ We are done with this issue.
+Rejected
+ We don't think this is a legitimate issue, and reject it entirely
+Can't Reproduce
+ We believe you, but we can't reproduce the behavior this issue refers to, so we can't do anything with it

Priorities
----------

+How important it is for us to get this issue fixed.
+
- Low
- Normal
- High
@@ -58,6 +71,8 @@ Priorities
Categories
----------

+Categories simply describe the general area or topic of an issue, categories may change with time depending on the project's needs.
+
Difficulty
----------


diff --git a/docs/source/dev/process.rst b/docs/source/dev/process.rst
index 2ede7a3..7f248c5 100644
--- a/docs/source/dev/process.rst
+++ b/docs/source/dev/process.rst
@@ -1,42 +1,40 @@
.. _process:

-Development Process
-===================
-.. todo::
- link to cycle, versions
- link to dev guide
+OSL Development Process
+=======================

+This document describes the general process the OSL uses for developing and maintaining projects.

Issue Triage
------------

-When an issue is reported on code.osuosl.org, the core team will try to triage the issue, assigning it to a release version or rejecting it, sending it back for more information. This process may take place as part of planning for a new version release, or ad hoc in order to address an important bug in the current release.
+When an issue is reported on code.osuosl.org, the core team will triage the issue, assigning it to a release version, rejecting it, or sending it back for more information. This process may take place as part of planning for a new version release, or ad hoc in order to address an important bug in the current release.

Features
~~~~~~~~

-Features will be considered only for the next minor or major version release. If the current release cycle has not yet reached the 'feature freeze' deadline, the feature may be considered for the current release, otherwise it should be assigned for a future release.
+Features will be considered only for the next minor or major version release. If the current release cycle has not yet reached the 'feature freeze' deadline, the feature may be considered for the current release; otherwise it should be assigned to a future release.

Enhancements
~~~~~~~~~~~~

-Enhancements will not be considered for the current version past its feature freeze date. Enhancement issues must apply to a current existing feature, if they introduce new basic functionality, they should be reclassified as Features. If they address malfunctioning code or incorrect functionality, they should be reclassified as Bugs.
+Enhancements will not be considered for the current version after that version's feature freeze date. Enhancement issues must apply to a current existing feature, if they introduce new basic functionality, they should be reclassified as Features. If they address malfunctioning code or incorrect functionality, they should be reclassified as Bugs.

Bugs
~~~~

-Bugs may be assigned to a release at any time. If they apply to an existing released version, this should generate a new point version. For example, a fix to the 0.10.1 release should generate a 0.10.2 release to contain the changes.
+Bugs may be assigned to a release at any time. If they apply to an existing released version, either a new point release must be created, or the bug must be incorporated into the next major or minor release. For example, an urgent fix to the 0.10.1 release should generate a 0.10.2 release to contain the changes. A less urgent fix for 0.10.1 might simply be incorporated into 0.11. In general, we try to collect multiple fixes into any point or minor release.


Workflow
--------

-The following work flow should be followed when contributing code.
+The following workflow should be followed when contributing code.

Assignment
~~~~~~~~~~

-Issues are assigned to developers in several ways
+Issues are assigned to developers in several ways:

- direct assignment by the project lead
- volunteer self-assignment
@@ -168,18 +166,4 @@ If work is done on GitHub or on an external repository rather than the OSL Gitol

Pull requests will be subject to the same review process outlined above, and should correspond to an issue in the OSL issue tracker. If no such issue exists, it must be created before accepting the pull request. When the pull request is approved, a new branch will be created following the normal naming conventions, and the work pulled into this branch. From this point, the work follows the same workflow as above.

-If the original developer does not have or is not willing to create an account on the OSL tracker, and the issue needs to be assigned back for additional work, such assignment may be communicated via email, an issue on the Github issue tracker for the developers' clone. If the developer is not willing to participate in this process, a core developer may be assigned to adopt the work, and the issue will be assigned to that developer for further work.
-
-
-Testing
--------
-
-
-Cleaning Up
------------
-
-Release Process
----------------
-
-
-
+If the original developer does not have or is not willing to create an account on the OSL tracker, and the issue needs to be assigned back for additional work, such assignment may be communicated via email, an issue on the Github issue tracker for the developers' clone. If the developer is not willing to participate in this process, a core developer may be assigned to adopt the work, and the issue will be assigned to that developer for further work.
\ No newline at end of file

diff --git a/docs/source/index.rst b/docs/source/index.rst
index efe54f3..9c9ffd5 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -115,7 +115,8 @@ References
ref/setup-script
ref/build-script
ref/venv
-
+ ref/search
+
Deprecated
==========
.. toctree::

diff --git a/docs/source/dev/search.rst b/docs/source/ref/search.rst
similarity index 100%
rename from docs/source/dev/search.rst
rename to docs/source/ref/search.rst