D89.1775289989.diff
No OneTemporary
Actions

Authored By

Unknown

Size

57 KB

Referenced Files

None

Subscribers

None

D89.1775289989.diff
View Options

	diff --git a/source/_static/kolab.css b/source/_static/kolab.css
	--- a/source/_static/kolab.css
	+++ b/source/_static/kolab.css
	@@ -131,6 +131,50 @@
	font-style: italic;
	}

	+span.blue {
	+ background: #dee7f8 none repeat scroll 0 0;
	+ border: 1px solid transparent;
	+ border-color: #cfdbe3;
	+ border-radius: 3px;
	+ color: #464c5c;
	+/* font-size: 12px; */
	+ padding: 0 4px;
	+}
	+
	+/*
	+ * span.blue::before {
	+ * content: " ";
	+ * font-family: FontAwesome;
	+ * }
	+ */
	+
	+span.gray {
	+ background: #edeef2 none repeat scroll 0 0;
	+ border: 1px solid transparent;
	+ border-color: #e3e4e8;
	+ border-radius: 3px;
	+ color: #555;
	+ padding: 0 4px;
	+}
	+
	+span.orange {
	+ background: #fbede1 none repeat scroll 0 0;
	+ border: 1px solid transparent;
	+ border-color: #f8dcc3;
	+ color: #ba6016;
	+ border-radius: 3px;
	+ padding: 0 4px;
	+}
	+
	+span.red {
	+ background: #f7e6e6 none repeat scroll 0 0;
	+ border: 1px solid transparent;
	+ border-color: #efcfcf;
	+ border-radius: 3px;
	+ color: #a53737;
	+ padding: 0 4px;
	+}
	+
	table.highlighttable {
	width: 100%;
	}
	diff --git a/source/conf.py b/source/conf.py
	--- a/source/conf.py
	+++ b/source/conf.py
	@@ -361,7 +361,7 @@

	# add variables as substitutions to the head of each page
	rst_prolog = ""
	-for var,repl in variables.items():
	+for var, repl in variables.items():
	rst_prolog += " .. \|%s\| replace:: %s\n" % (var, repl)
	rst_prolog += " .. \|%s\| replace:: %s\n" % (var, repl)

	@@ -377,6 +377,9 @@

	rst_prolog += """
	.. _Architecture & Design: https://git.kolab.org/tag/architecture_design/
	+.. _bugzilla: https://issues.kolab.org/
	+.. _current sprint: https://git.kolab.org/tag/sprint_current/
	+.. _next sprint: https://git.kolab.org/tag/sprint_next/
	.. _Differential: https://git.kolab.org/differential/
	.. _Diffusion: https://git.kolab.org/diffusion/
	.. _Drydock: https://git.kolab.org/drydock/
	@@ -391,7 +394,17 @@
	.. _Product Owners: https://git.kolab.org/tag/product_owners/
	.. _Projects: https://git.kolab.org/projects/
	.. _Quality Assurance: https://git.kolab.org/tag/quality_assurance/
	+.. _Report a bug: https://git.kolab.org/maniphest/task/edit/form/9/
	+.. _Scrum: http://en.wikipedia.org/wiki/Scrum_%28software_development%29
	.. _Scrum Masters: https://git.kolab.org/tag/process_managers/
	.. _Sprints: https://git.kolab.org/project/sprint/
	.. _Why Your System Should Have a Proper FQDN: https://kanarip.wordpress.com/2016/02/04/why-your-system-requires-a-proper-fqdn/
	"""
	+
	+rst_prolog += """
	+.. role:: blue
	+.. role:: gray
	+.. role:: green
	+.. role:: orange
	+.. role:: red
	+"""
	diff --git a/source/contributor-guide/bug-reporting-casual.rst b/source/contributor-guide/bug-reporting-casual.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/bug-reporting-casual.rst
	@@ -0,0 +1,29 @@
	+============================
	+Reporting Bugs Against Kolab
	+============================
	+
	+For the version of Kolab you are running, it is assumed that the issue you are
	+running in to exists in both your version, and the next version of Kolab (i.e.
	+the development version).
	+
	+At the time of this writing, this can be :orange:`Kolab 16` (stable) or
	+:orange:`Winterfell` (development).
	+
	+Therefore, `report a bug`_ against Kolab in Phabricator. You'll describe what
	+it is you did, what the expected results are, what results you got, and how
	+those results do not meet your expectations.
	+
	+It is assumed all bugs are issues in the development of Kolab, for two main
	+reasons:
	+
	+* Development teams need to ensure the software is tested for the issue you
	+ find.
	+
	+* The bug zappers are able to assist you with troubleshooting, suggesting
	+ work-arounds, configuration, and providing the necessary information.
	+
	+.. seealso::
	+
	+ * :ref:`contributor-guide-structured-contributions-reporting-bugs`
	+
	+Return to other :ref:`contributor-guide-casual-contributions` you could make.
	diff --git a/source/contributor-guide/bug-reporting-structured.rst b/source/contributor-guide/bug-reporting-structured.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/bug-reporting-structured.rst
	@@ -0,0 +1,154 @@
	+.. _contributor-guide-structured-contributions-reporting-bugs:
	+
	+===========================================================
	+Reporting Bugs Against (Long-Term) Supported Kolab Versions
	+===========================================================
	+
	+Long-term support versions of Kolab maintain larger sets of different versions
	+of software, and it becomes important to ensure that the fix for an issue in
	+`foo-1.0` does not require a properly entitled customer to upgrade to a later
	+version of Kolab, or even a later version of `foo`.
	+
	+The stability requirements imply that support be able to track issues with
	+specific versions of the software, targets these issues to be resolved in
	+certain newer versions of the software, and trusts the resolution of the issue
	+to be verifiable against multiple versions of the software collection.
	+
	+Example
	+=======
	+
	+The following table depicts the versions of the roundcubemail package, and
	+the roundcubemail-plugins-kolab package, as distributed for each product
	+stream.
	+
	+.. table:: Version table for Roundcubemail and Kolab Plugins
	+
	+ +-------------------------------+---------------+-----------------------------+
	+ \| \| roundcubemail \| roundcubemail-plugins-kolab \|
	+ +===============================+===============+=============================+
	+ \| :orange:`Kolab Enterprise 13` \| `1.0.4` \| `3.1.16` \|
	+ +-------------------------------+---------------+-----------------------------+
	+ \| :orange:`Kolab Enterprise 14` \| `1.1.4` \| `3.2.11` \|
	+ +-------------------------------+---------------+-----------------------------+
	+ \| :orange:`Kolab 16` \| `1.2` \| `3.3` \|
	+ +-------------------------------+---------------+-----------------------------+
	+ \| :orange:`Kolab Winterfell` \| `1.2` \| `3.3` \|
	+ +-------------------------------+---------------+-----------------------------+
	+
	+Stability requirements for :orange:`Kolab Enterprise 13` demand the following:
	+
	+* The version of roundcubemail shipped to the product stream is one of
	+ the 1.0 series of upstream releases,
	+
	+* Upstream maintains a stable 1.0 series for roundcubemail,
	+
	+* The version of roundcubemail-plugins-kolab shipped to the product
	+ stream is one of the 3.1 series of upstream releases,
	+
	+* Upstream maintains a stable 3.1 series for roundcubemail-plugins-kolab,
	+
	+* Future versions of roundcubemail in the 1.0 series remain backward
	+ compatibility for consumers of its API (such as
	+ roundcubemail-plugins-kolab),
	+
	+* Added functionality in roundcubemail-plugins-kolab, if any, does not
	+ require any changes in roundcubemail that would break other compatibility,
	+
	+* The aforementioned conditions all last for up to 5 years,
	+
	+* For a large number of target platforms.
	+
	+The same conditions apply to :orange:`Kolab Enterprise 14` and
	+:orange:`Kolab 16` -- with different version series, different timelines and
	+sometimes different stacks.
	+
	+Further down the dependency stack, this includes maintenance for
	+libkolabxml, libkolab and libcalendaring.
	+
	+In the future, this will extend up to 6 product streams that will need to be
	+maintained.
	+
	+It is therefore important that an issue logged against a version 1.0.1, with
	+the current version in the 1.0 series perhaps being 1.0.10, needs to go through
	+the following stages:
	+
	+#. Is the issue reproducible in the unstable development version of the
	+ software suite?
	+
	+ a. If it is, it is a development issue; `report a bug`_ in Phabricator.
	+
	+ Developer teams become responsible for testing the resolution of the
	+ issue first, and fixing the issue second (see
	+ :ref:`contributor-guide-test-driven-development`).
	+
	+ For each of the product streams in between current development and
	+ the original issue report, create a ticket in `bugzilla`_.
	+
	+ .. seealso::
	+
	+ * Something about backporting with the verification included.
	+
	+ b. If it is not, in what product stream can the issue still be reproduced?
	+
	+ This process can be very costly lather-rinse-repeat exercise, and
	+ therefore needs to be covered ahead of time, through
	+ :ref:`contributor-guide-test-driven-development`.
	+
	+ Create a `bugzilla`_ ticket for the appropriate
	+
	+ .. seealso::
	+
	+ * Something about constructive troubleshooting efforts
	+
	+#. Using the input of 1) and outcome of 1a) or 1b), describe the range of
	+ targets;
	+
	+ * branch 1.2 for :orange:`Kolab 16`: yes or no?
	+ * branch 1.1 for :orange:`Kolab Enterprise 14`: yes or no?
	+ * etc.
	+
	+ Each becomes a separate `bugzilla`_ ticket, each of them depending on the
	+ resolution of the more recent product stream('s software version).
	+
	+Example
	+=======
	+
	+Let's assume "yay" fails on all versions of Roundcube.
	+
	+#. Issue:
	+
	+ Yay fails on Roundcube 1.0.1 on :gray:`Enterprise Linux 6`
	+
	+ This is an original ticket. The intended milestone for the resolution is
	+ `1.0-next`.
	+
	+#. Support:
	+
	+ #. Does yay fail in :orange:`Kolab Winterfell` on Enterprise Linux 7?
	+
	+ Yes, this is a new development issue; `Report a bug`_. Add a project
	+ tag for :orange:`Winterfell`
	+
	+ #. Does yay fail in :orange:`Kolab 16` on Enterprise Linux 7?
	+
	+ Yes, and :orange:`Kolab 16` is on the same software version series as
	+ :orange:`Winterfell`;
	+
	+ It is thus a new development issue; `Report a bug`_ and have it
	+ blocked by the bug created in 2.1).
	+
	+ Associate the :orange:`Kolab 16` release target with the bug.
	+
	+ Also create a `bugzilla`_ ticket. The milestone here is `1.2-next`.
	+ Refer to the task created in Phabricator.
	+
	+ #. Does yay fail in :orange:`Kolab Enterprise 14` on
	+ :gray:`Enterprise Linux 6` ?
	+
	+ Yes, create a `bugzilla`_ ticket and block it with the ticket created
	+ in 2.2). The milestone here is `1.1-next`.
	+
	+ #. Does yay fail in :orange:`Kolab Enterprise 13` on
	+ :gray:`Enterprise Linux 6` using version 1.0.4?
	+
	+ Yes, block the original ticket in 1) with the ticket from 2.3).
	diff --git a/source/contributor-guide/continuous-integration.rst b/source/contributor-guide/continuous-integration.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/continuous-integration.rst
	@@ -0,0 +1,3 @@
	+================================
	+(Ab)using Continuous Integration
	+================================
	diff --git a/source/contributor-guide/docker-containers.rst b/source/contributor-guide/docker-containers.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/docker-containers.rst
	@@ -0,0 +1,4 @@
	+=================================
	+Run Kolab Using Docker Containers
	+=================================
	+
	diff --git a/source/contributor-guide/documentation/index.rst b/source/contributor-guide/documentation/index.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/documentation/index.rst
	@@ -0,0 +1,76 @@
	+.. _contributor-guide-documentation:
	+
	+=================================
	+Contributing to the Documentation
	+=================================
	+
	+This documentation can easily be contributed to by cloning the following git
	+repository.
	+
	+ https://git.kolab.org/diffusion/D/docs.git
	+
	+.. IMPORTANT::
	+
	+ The documentation is only as good as your willingness to contribute
	+ to it.
	+
	+Other documentation included here:
	+
	+.. toctree::
	+ :maxdepth: 1
	+
	+ writing-documentation
	+ todolist
	+
	+Building the Documentation
	+==========================
	+
	+Most of our more regular contributors clone the repository to their
	+local workstation, and then build the documentation before pushing back
	+changes to their fork of kolab-docs. To build the documentation, you
	+need to have `Sphinx`_ installed. You can also find some hints, tips and
	+tricks on their website, with regards to the `reStructuredText`_ format
	+the documentation is written in.
	+
	+#. Naturally, first clone the git repository.
	+
	+ .. parsed-literal::
	+
	+ $ :command:`git clone https://git.kolab.org/diffusion/D/docs.git`
	+
	+#. Navigate in to the fresh clone:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`cd docs`
	+
	+#. To build the documentation, issue the following command:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`make html`
	+
	+#. Make some changes, and build and view the result:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`make html`
	+ $ :command:`xdg-open build/html/index.html`
	+
	+#. When you are satisfied, commit the results and submit a `Differential`_:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`git commit -a`
	+ $ :command:`arc diff`
	+
	+#. Push your changes back into our Phabricator instance.
	+ Timotheus wrote `a good tutorial on how to do that <http://www.pokorra.de/2015/07/submitting-patches-to-kolab-via-phabricator/>`_.
	+
	+Enjoy and thanks for contributing to Kolab!
	+
	+.. _Sphinx: http://sphinx-doc.org/
	+.. _reStructuredText: http://sphinx-doc.org/rest.html
	+.. _Working with Git Submodules: http://git-scm.com/book/en/Git-Tools-Submodules
	+.. _docs.kolab.org: https://docs.kolab.org
	+
	diff --git a/source/contributor-guide/documentation/todolist.rst b/source/contributor-guide/documentation/todolist.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/documentation/todolist.rst
	@@ -0,0 +1,12 @@
	+Possible Contributions
	+======================
	+
	+The following list is a collection of all the places where a todo item was included,
	+because there is more work to do.
	+Please consider picking one of those up helping to complete the documentation.
	+
	+That's left to do:
	+------------------
	+
	+.. todolist::
	+
	diff --git a/source/contributor-guide/documentation/writing-documentation.rst b/source/contributor-guide/documentation/writing-documentation.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/documentation/writing-documentation.rst
	@@ -0,0 +1,59 @@
	+.. _dev-writing-documentation:
	+
	+=====================
	+Writing Documentation
	+=====================
	+
	+The Kolab community has a reference implementation of its releases,
	+which can best be described as a next-next-finish installation [#]_
	+of a single node [#]_ running Enterprise Linux 7 [#]_.
	+
	+For writing documentation, this means that all documented commands and
	+file paths mentioned need to match that specific implementation [#]_ of
	+Kolab installed on Enterprise Linux 7, and that every HOWTO needs to
	+start at the aforementioned null situation.
	+
	+This sounds harsh, and it probably is, but here's how you can work with
	+it:
	+
	+* When you create a HOWTO for something on Debian, your HOWTO should
	+ probably be titled: HOWTO: Achieve Greatness (on Debian Wheezy).
	+
	+* When you do write a generic HOWTO, you can re-iterate the commands
	+ issued for different distributions::
	+
	+ After changing the configuration, restart the service:
	+
	+ .. parsed-literal::
	+
	+ # :command:`systemctl restart postfix`
	+
	+ On Debian Wheezy, execute the following instead:
	+
	+ .. parsed-literal::
	+
	+ # :command:`/etc/init.d/postfix restart`
	+
	+.. rubric:: Footnotes
	+
	+.. [#]
	+
	+ This means to confirm the default settings (other than perhaps the
	+ passwords) during :ref:`installation-guide-setup-kolab`, including but not
	+ limited to the characters used in the passwords chosen -- while we
	+ have learned of issues when using passwords with special characters,
	+ which relate to third party application defaults.
	+
	+.. [#]
	+
	+ A single node is a single operating system instance; physical,
	+ virtual, docked or contained.
	+
	+.. [#]
	+
	+ In the family of Enterprise Linux 7 distributions that we provide
	+ packages for are Red Hat Enterprise Linux and CentOS.
	+
	+.. [#]
	+
	+ The specific implementation is a single-node deployment topology.
	diff --git a/source/contributor-guide/feature-requests/index.rst b/source/contributor-guide/feature-requests/index.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/feature-requests/index.rst
	@@ -0,0 +1,91 @@
	+.. _contributor-guide-feature-requests:
	+
	+================
	+Feature Requests
	+================
	+
	+The Definition of a Feature Request
	+===================================
	+
	+A feature request is a description of a problem space for which we may seek the
	+resolution to be provided within, or with the help of, Kolab.
	+
	+Such a problem space is articulated in and by itself, and allows for
	+understanding to be formed and interpretation to be fine-tuned over the course
	+of a process with multiple parties contributing.
	+
	+.. IMPORTANT::
	+
	+ Using problem spaces re-inforces the importance of the human
	+ experience for the final product enhancement.
	+
	+A bad example of a feature request would be:
	+
	+ Make the button background red.
	+
	+This example neither addresses the actual problem, nor the potential value of a
	+resolution.
	+
	+A better example would be:
	+
	+ The contrast between the button background and page is too low.
	+
	+Any target use-case or workflow described must be considered only as a context
	+establishing a higher level of comprehension in elaboration, about the
	+dimensions of the problem space. Per the existing example:
	+
	+ *Color vision deficiencies do not allow some people to distinguish the
	+ button from the background.*
	+
	+This would allow us to clarify whether a high-contrast UI is needed, or a
	+slight adjustment suffices. We would also get to cover other angles.
	+
	+Feature requests without a sufficiently accurate or encompassing description of
	+the problem space to address will not be accepted.
	+
	+Where Do Feature Requests Go?
	+=============================
	+
	+Feature requests can be entered in to the Kolab development platform using `this
	+form <https://git.kolab.org/maniphest/task/edit/form/12/>`_.
	+
	+It's submitted to the backlog of the :red:`Architecture & Design` team.
	+
	+The `Architecture & Design`_ team evaluates the enhancement requests, requests
	+additional feedback if needed, and assigns the priority should the request be
	+promoted.
	+
	+The responsibility of this team is to ensure that, before the construction phase;
	+
	+* we have an accurate and full problem space description, and
	+
	+* we understand the scope and dimensions of the problem space, and
	+
	+* we can successfully determine where the problem should be resolved, and
	+
	+* we can determine the resolution to this problem space makes sense for the
	+ product that is Kolab, or
	+
	+* we can determine that the problem space is better addressed by existing,
	+ external tooling, and find a means for that external tooling to be
	+ integrated with Kolab, or
	+
	+* we can determine that addressing the problem space does not enhance the
	+ Kolab product, and
	+
	+* an estimate value of resolving the problem space can be established.
	+
	+This leads to a common understanding of scope of delivery, the definition of
	+done, and the way to verify the results.
	+
	+Backlog
	+
	+Inception
	+
	+Elaboration
	+
	+Construction
	+
	+Transition
	+
	+.. This part of the process is called :ref:`developer-guide-process-inception`.
	diff --git a/source/contributor-guide/getting-started.rst b/source/contributor-guide/getting-started.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/getting-started.rst
	@@ -0,0 +1,84 @@
	+.. _contributor-guide-getting-started:
	+
	+================================
	+Getting Started with Phabricator
	+================================
	+
	+#. Navigate to https://git.kolab.org. We recommend you use a browser.
	+
	+#. Determine whether you are a Kolab Systems employee, and act accordingly;
	+
	+ #. If you are a Kolab Systems employee, use your corporate credentials to
	+ login using LDAP.
	+
	+ #. If you are not a Kolab Systems employee, create yourself an account if
	+ you have not already done so. You can use any of the forms except for
	+ the one that requests LDAP credentials.
	+
	+#. `Set your date-time notation format <https://git.kolab.org/settings/panel/datetime>`_.
	+
	+#. Set your profile picture.
	+
	+#. `Upload an SSH public key <https://git.kolab.org/settings/panel/ssh/>`_.
	+
	+#. `Set your text-area font to fixed width <https://git.kolab.org/settings/panel/display/>`_.
	+
	+#. `Configure email notifications <https://git.kolab.org/settings/panel/emailpreferences/>`_,
	+ especially the ones for actions you place yourself.
	+
	+#. :ref:`contributor-guide-setup-tools`.
	+
	+#. Hook up arcanist to your Phabricator account:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`arc install-certificate`
	+
	+Projects
	+========
	+
	+Software development projects use a communication icon (envelope) in
	+:blue:`blue`.
	+
	+Each software development project is provided a workboard, such they could, at
	+their option, visualize a roadmap.
	+
	+.. NOTE::
	+
	+ The use of sub-projects and milestones in Phabricator is under review.
	+
	+Teams
	+=====
	+
	+Teams include groups of people that work on software development projects, or
	+form the :red:`Architecture & Design` team, :red:`Release Managers`, etc.
	+
	+Membership of these teams usually provides you with commit access to a GIT
	+repository, and is used to authorize differentials in
	+:ref:`contributor-guide-peer-review`.
	+
	+* Software developer teams are used to authorize commit access, and use a group icon in :red:`red`.
	+
	+* You need to request membership from one of the existing members.
	+
	+* You only need membership in order to push to the GIT repositories directly.
	+
	+Sprints
	+=======
	+
	+Sprints are time-boxed team efforts with the duration of exactly one week --
	+running from Monday morning to Friday afternoon.
	+
	+TODO: More about sprints
	+
	+Release Targets
	+===============
	+
	+Release targets are irrelevant for developers. The only release target that is
	+relevant for developers is :orange:`Winterfell`.
	+
	+Distributions
	+=============
	+
	+Distributions (target platforms) are irrelevant for developers. The only target
	+platform relevant to developers is :gray:`Maipo` (Enterprise Linux 7).
	diff --git a/source/contributor-guide/index.rst b/source/contributor-guide/index.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/index.rst
	@@ -0,0 +1,83 @@
	+.. _contributor-guide:
	+
	+=================
	+Contributor Guide
	+=================
	+
	+Kolab Groupware development largely follows an iterative and incremental
	+agile software development metholodogy also known as `Scrum`_.
	+
	+In summary, the development process is divided into stages, with different
	+teams participating in getting tasks to the next stage of the process.
	+
	+Kolab Groupware is a collaboration suite consisting of many components,
	+each of them separate software development projects, some of them
	+dependent on third-party software development projects, and some of them
	+separate altogether.
	+
	+.. IMPORTANT::
	+
	+ Still to do:
	+
	+ * Contributing to translations (l10n and i18n)
	+
	+ * Switch current documentation stuff over
	+
	+ * Fixing packaging issues
	+
	+ * Feature requests' inception/elaboration/construction/transition
	+ phases
	+
	+ * Testing Kolab
	+
	+ * Participation section on Peer Review -- the actual execution of
	+ things.
	+
	+ Note that this includes the applying of a differential to review
	+ the work in its full context.
	+
	+ * Running docker containers
	+
	+ * (Ab)using Continuous Integration (fully testing locally)
	+
	+ * SCRUM details
	+
	+ * Packaging and Continuous Delivery
	+
	+.. _contributor-guide-casual-contributions:
	+
	+Casual Contributions
	+====================
	+
	+The following guides are intended for casual contributors and contributions,
	+such as a one-time 5-line patch for that one itch to scratch.
	+
	+.. toctree::
	+ :maxdepth: 1
	+
	+ translations
	+ bug-reporting-casual
	+ documentation/index
	+ packaging/casual
	+ feature-requests/index
	+ testing
	+
	+.. _contributor-guide-structured-contributions:
	+
	+Structured Contributions
	+========================
	+
	+The following guides set you up for regular, structured contributions to Kolab,
	+such as continued development and participation in sprints.
	+
	+.. toctree::
	+ :maxdepth: 1
	+
	+ getting-started
	+ setup-development-environment
	+ peer-review
	+ docker-containers
	+ continuous-integration
	+ scrum
	+ packaging
	+ bug-reporting-structured
	diff --git a/source/contributor-guide/packaging.rst b/source/contributor-guide/packaging.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/packaging.rst
	@@ -0,0 +1,3 @@
	+=================================
	+Packaging and Continuous Delivery
	+=================================
	diff --git a/source/contributor-guide/packaging/casual.rst b/source/contributor-guide/packaging/casual.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/packaging/casual.rst
	@@ -0,0 +1,4 @@
	+=======================
	+Fixing Packaging Issues
	+=======================
	+
	diff --git a/source/contributor-guide/peer-review.rst b/source/contributor-guide/peer-review.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/peer-review.rst
	@@ -0,0 +1,33 @@
	+.. _contributor-guide-peer-review:
	+
	+===========
	+Peer Review
	+===========
	+
	+Peer review is a process in which developers submit code changes to a staging
	+environment, so that other peers have the opportunity to review the work before
	+the code changes are submitted back to the source code management repository.
	+
	+In our development platform, this process is facilitated by `Differential`_. To
	+use `Differential`_, you must install arcanist and set it up.
	+
	+.. seealso::
	+
	+ * :ref:`contributor-guide-setup-your-development-environment`
	+
	+In Kolab development, this stage allows work to progress on writing tests that
	+fail, first, subsequently supplemented by the work on code changes that make
	+those tests succeed.
	+
	+.. seealso::
	+
	+ * :ref:`contributor-guide-test-driven-development`
	+
	+The changes submitted are reviewed on Thursday afternoons at the latest.
	+
	+Your changes need to be reviewed by at least one other person, who is a
	+software development project member.
	+
	+In :ref:`contributor-guide-test-driven-development`, the submission of the
	+differential associated with your review process aides in the staging of the
	+code changes.
	diff --git a/source/contributor-guide/scrum.rst b/source/contributor-guide/scrum.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/scrum.rst
	@@ -0,0 +1,17 @@
	+=====
	+SCRUM
	+=====
	+
	+Our agile development process is time-boxed with sprints.
	+
	+.. toctree::
	+ :maxdepth: 1
	+
	+ scrum/sprints
	+
	+.. toctree::
	+ :maxdepth: 1
	+
	+ scrum/start-of-sprint-checklist
	+ scrum/during-the-sprint
	+ scrum/end-of-sprint-checklist
	diff --git a/source/contributor-guide/scrum/during-the-sprint.rst b/source/contributor-guide/scrum/during-the-sprint.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/scrum/during-the-sprint.rst
	@@ -0,0 +1,3 @@
	+=================
	+During the Sprint
	+=================
	diff --git a/source/contributor-guide/scrum/end-of-sprint-checklist.rst b/source/contributor-guide/scrum/end-of-sprint-checklist.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/scrum/end-of-sprint-checklist.rst
	@@ -0,0 +1,33 @@
	+=======================
	+End of Sprint Checklist
	+=======================
	+
	+* The `current sprint`_ must be archived after Friday, 17:00 CET.
	+
	+* The `current sprint`_ must have its additional ``#sprint_current``
	+ hashtag removed.
	+
	+* Tickets that remain open in the `current sprint`_ must be moved forward
	+ on to the `next sprint`_.
	+
	+ .. NOTE::
	+
	+ The column for these tickets in the `current sprint`_ should be
	+ reflected in the `next sprint`_, which requires manual intervention.
	+
	+* The `next sprint`_ becomes the current sprint, and thus:
	+
	+ * Remove the additional hashtag ``#sprint_next``,
	+
	+ * Add the additional hashtag ``#sprint_curret``.
	+
	+* The sprint after the next sprint needs to be created;
	+
	+ * The sprint runs from a Monday 09:00 AM to the following Friday 05:00
	+ PM.
	+
	+ * Use an additional hashtag of ``#sprint_next``.
	+
	+* Verify the (now) `current sprint`_ (but actually next week's) actually has
	+ sufficient tickets in its backlog, because idling is for jet engines with
	+ reverse thrusters deployed while in flight.
	diff --git a/source/contributor-guide/scrum/sprints.rst b/source/contributor-guide/scrum/sprints.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/scrum/sprints.rst
	@@ -0,0 +1,3 @@
	+=======
	+Sprints
	+=======
	diff --git a/source/contributor-guide/scrum/start-of-sprint-checklist.rst b/source/contributor-guide/scrum/start-of-sprint-checklist.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/scrum/start-of-sprint-checklist.rst
	@@ -0,0 +1,9 @@
	+=========================
	+Start of Sprint Checklist
	+=========================
	+
	+* Contributors assign story points to the tickets in the backlog.
	+
	+* Product owners prioritize tickets.
	+
	+* A sprint planning meeting provides the opportunity to talk things over.
	diff --git a/source/contributor-guide/setup-development-environment.rst b/source/contributor-guide/setup-development-environment.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/setup-development-environment.rst
	@@ -0,0 +1,309 @@
	+.. _contributor-guide-setup-your-development-environment:
	+
	+==================================
	+Setup Your Development Environment
	+==================================
	+
	+This guide sets you up a development workstation to contribute to Kolab
	+Groupware development on `Phabricator`_.
	+
	+#. :ref:`contributor-guide-setup-tools`
	+
	+.. _contributor-guide-setup-tools:
	+
	+Install the Tools
	+=================
	+
	+#. Ensure you have our Tools repository configured.
	+
	+ .. parsed-literal::
	+
	+ # :command:`cd /etc/yum.repos.d/`
	+
	+ For Fedora 23:
	+
	+ .. parsed-literal::
	+
	+ # :command:`wget https://obs.kolabsys.com/repositories/Tools/Fedora_23/Tools.repo`
	+
	+ For Fedora 22:
	+
	+ .. parsed-literal::
	+
	+ # :command:`wget https://obs.kolabsys.com/repositories/Tools/Fedora_22/Tools.repo`
	+
	+ For Red Hat Enterprise Linux 7:
	+
	+ .. parsed-literal::
	+
	+ # :command:`wget https://obs.kolabsys.com/repositories/Tools/RHEL_7/Tools.repo`
	+
	+#. Import the GPG public key the packages are signed with:
	+
	+ .. parsed-literal::
	+
	+ # :command:`rpm --import https://ssl.kolabsys.com/community.asc`
	+
	+#. Install arcanist:
	+
	+ For Fedora 22 and Fedora 23:
	+
	+ .. parsed-literal::
	+
	+ # :command:`dnf -y install arcanist`
	+
	+ For Red Hat Enterprise Linux 7:
	+
	+ .. parsed-literal::
	+
	+ # :command:`yum -y install arcanist`
	+
	+.. _contributor-guide-setup-recommended-configuration:
	+
	+Recommended Configuration
	+=========================
	+
	+SSH Configuration
	+
	+ Configure SSH to use the correct username and SSH identity when you use
	+ ``git.kolab.org``:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`grep -A3 git.kolab.org ~/.ssh/config`
	+ Host git.kolab.org
	+ User git
	+ IdentityFile ~/.ssh/id_rsa
	+
	+BASH Completion
	+
	+ Say something about bash completion and how great it is.
	+
	+GIT Prompt
	+
	+ Say something about the git prompt.
	+
	+GIT Configuration
	+
	+ For each repository separately, or otherwise globally:
	+
	+ .. parsed-literal::
	+
	+ $ :command:`git config [--global] user.name "Jeroen van Meeuwen (Kolab Systems)"`
	+ $ :command:`git config [--global] user.email vanmeeuwen\@kolabsys.com`
	+ $ :command:`git config [--global] branch.autosetuprebase always`
	+ $ :command:`git config [--global] push.default matching`
	+
	+~/.bashrc
	+
	+A recommended snippet for `~/.bashrc` to assist you visually:
	+
	+.. parsed-literal::
	+
	+ export GIT_PS1_SHOWDIRTYSTATE=1
	+ export GIT_PS1_SHOWUNTRACKEDFILES=1
	+ export GIT_PS1_SHOWUPSTREAM="auto verbose"
	+
	+ if [ ! -f "/etc/bash_completion" ]; then
	+ if [ -f "/etc/bash_completion.d/git" ]; then
	+ cp /etc/bash_completion.d/git ~/.git-completion.sh
	+ . ~/.git-completion.sh
	+ PS1='[\u\@\h \W$(__git_ps1 " (%s)")]\$ '
	+ elif [ -f "/usr/share/bash-completion/completions/git" ]; then
	+ cp /usr/share/bash-completion/completions/git ~/.git-completion.sh
	+ . ~/.git-completion.sh
	+ PS1='[\u\@\h \W$(__git_ps1 " (%s)")]\$ '
	+ fi
	+ else
	+ PS1='[\u\@\h \W$(__git_ps1 " (%s)")]\$ '
	+ fi
	+
	+ if [ -f "/usr/share/git-core/contrib/completion/git-prompt.sh" ]; then
	+ source /usr/share/git-core/contrib/completion/git-prompt.sh
	+ fi
	+
	+This makes your shell navigating in to a GIT repository appear as follows:
	+
	+#. :command:`cd` in to a GIT repository:
	+
	+ .. parsed-literal::
	+
	+ [kanarip\@dws06 ~]$ :command:`cd ~/devel/puppet/domains/kolabsys.com`
	+ [kanarip\@dws06 kolabsys.com (development u=)]$
	+
	+ This means a clean working copy.
	+
	+#. Create an untracked file:
	+
	+ .. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (development u=)]$ :command:`touch something`
	+ [kanarip\@dws06 kolabsys.com (development % u=)]$
	+
	+ THe `%` means untracked files exist in the directory hierarchy.
	+
	+#. Add the untracked file:
	+
	+ .. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (development % u=)]$ :command:`git add something`
	+ [kanarip\@dws06 kolabsys.com (development + u=)]$
	+
	+ The `+` means tracked, uncommitted files exist in the directory hierarchy.
	+
	+#. Change a file:
	+
	+ .. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (development + u=)]$ :command:`echo 1 > something`
	+ [kanarip\@dws06 kolabsys.com (development \*+ u=)]$
	+
	+ The `*` means uncommitted changes to tracked files exist. The `+` still
	+ indicates a tracked file is not yet committed.
	+
	+#. Checkout another branch. In this example, it is specifically made dirty to
	+ show off:
	+
	+ .. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (development \*+ u=)]$ :command:`git checkout testing`
	+ A something
	+ Switched to branch 'testing'
	+ Your branch and 'origin/testing' have diverged,
	+ and have 4 and 65 different commits each, respectively.
	+ (use "git pull" to merge the remote branch into yours)
	+ [kanarip\@dws06 kolabsys.com (testing \*+ u+4-65)]$
	+
	+ This means we have 4 commits to our local working copy not yet in the
	+ remote tracked, and 65 commits in the remote tracked not yet in our local
	+ working copy.
	+
	+#. Attempt to rebase on top of the tracked remote:
	+
	+ .. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (testing \*+ u+4-65)]$ :command:`git rebase origin/testing --autostash`
	+ Created autostash: 49f31f4
	+ HEAD is now at a6fb106 Ensure docker runs on atomic hosts
	+ First, rewinding head to replay your work on top of it...
	+ Applied autostash.
	+ [kanarip\@dws06 kolabsys.com (testing + u=)]$
	+
	+ You'll notice the `+` again stands for the tracked, not yet committed file
	+ :file:`something`.
	+
	+Pushing Changes
	+===============
	+
	+There is virtually no need to push only to the development branch, but merging
	+and cherry-picking individual changes should be avoided:
	+
	+.. parsed-literal::
	+
	+ $ :command:`cd ~/devel/puppet/domains/kolabsys.net`
	+ (...make some changes...)
	+ $ :command:`git commit -a -m "Make some changes"`
	+
	+Attempt a push if you feel so inclined:
	+
	+.. parsed-literal::
	+
	+ $ :command:`git push origin development`
	+
	+This may be refused as a non-fast forward attempt, so fetch the origin first.
	+
	+.. IMPORTANT::
	+
	+ Do NOT just issue a :command:`git pull` if your prompt shows your
	+ current local working copy is not clean -- this can still result in a merge
	+ commit and those will not be allowed when pushing them back.
	+
	+.. parsed-literal::
	+
	+ $ :command:`git fetch origin`
	+ $ :command:`git rebase origin/development --autostash`
	+
	+Your prompt should now show something like:
	+
	+.. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (development u+1)]$
	+
	+To push your changes:
	+
	+.. parsed-literal::
	+
	+ $ :command:`git push origin development`
	+ $ :command:`git push origin development:testing`
	+ $ :command:`git push origin development:production`
	+
	+Creating a Differential for Review
	+==================================
	+
	+A standard repository comes with three branches: development, testing,
	+production.
	+
	+Make sure you have development checked out, and for the sake of preventing
	+superfluous merge and rebase exercises, ensure it's in sync with upstream:
	+
	+.. parsed-literal::
	+
	+ $ :command:`git checkout development`
	+ $ :command:`git fetch origin`
	+ $ :command:`git rebase origin/development --autostash`
	+
	+Make sure you have a ticket for `Engineering`_ for your work and
	+`Operations`_ for the final application to production systems.
	+
	+Given such a ticket, such as :task:`144`, you can branch off the GIT
	+repository;
	+
	+.. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.com (development u=)]$ :command:`git checkout -b T144`
	+ [kanarip\@dws06 kolabsys.com (T144)]$
	+
	+Make your changes, and commit them in however many commits you think is
	+reasonable.
	+
	+Then, create the `Differential`_:
	+
	+.. parsed-literal::
	+
	+ [kanarip\@dws06 kolabsys.net (T125 %)]$ arc diff
	+ You have untracked files in this working copy.
	+
	+ Working copy: /home/kanarip/devel/puppet/domains/kolabsys.net/
	+
	+ Untracked changes in working copy:
	+ (To ignore these changes, add them to ".git/info/exclude".)
	+ bin/reroute-vpn
	+ files/haproxy/haproxy.cfg.transparent
	+ haproxy.patch
	+ nodes
	+ puppet/manifests/classes/puppet.pp~HEAD
	+ puppet/manifests/classes/yum.pp.rej
	+
	+ Ignore these untracked files and continue? [y/N] :command:`y`
	+
	+You will now be requested to provide some information about your proposed
	+changes.
	+
	+Set the first ``Summary:`` line to ``Resolves T345678``, so that your
	+differential will be associated with the ticket automatically, and an accepted
	+differential also closes the ticket you refer to.
	+
	+.. parsed-literal::
	+
	+ Linting...
	+ No lint engine configured for this project.
	+ Running unit tests...
	+ No unit test engine is configured for this project.
	+ Updating commit message...
	+ Created a new Differential revision:
	+ Revision URI: https://noc.kolabsys.net/D8
	+
	+ Included changes:
	+ M puppet/manifests/classes/puppet.pp
	+
	+And that's it.
	diff --git a/source/contributor-guide/test-driven-development.rst b/source/contributor-guide/test-driven-development.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/test-driven-development.rst
	@@ -0,0 +1,19 @@
	+.. _contributor-guide-test-driven-development:
	+
	+=======================
	+Test-Driven Development
	+=======================
	+
	+Test-driven development is a process in the
	+:ref:`contributor-guide-phases-construction`.
	+
	+The process of development driven by testing can be transcribed as follows:
	+
	+#. You get handed a set of clear requirements -- mostly in the form of user
	+ stories you can verify, and documentation on the design -- architecture and
	+ mockups.
	+
	+#. You write the tests that verify those requirements are implemented.
	+
	+#. You write the code that makes the tests succeed.
	+
	diff --git a/source/contributor-guide/testing.rst b/source/contributor-guide/testing.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/testing.rst
	@@ -0,0 +1,3 @@
	+=============
	+Testing Kolab
	+=============
	diff --git a/source/contributor-guide/translations.rst b/source/contributor-guide/translations.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/contributor-guide/translations.rst
	@@ -0,0 +1,3 @@
	+==================================================
	+Translation: Localization and Internationalization
	+==================================================
	diff --git a/source/developer-guide/process.rst b/source/developer-guide/process.rst
	new file mode 100644
	--- /dev/null
	+++ b/source/developer-guide/process.rst
	@@ -0,0 +1,500 @@
	+.. _developer-guide-process:
	+
	+===================
	+Development Process
	+===================
	+
	+.. todo::
	+
	+ Describe continuous integration
	+
	+.. todo::
	+
	+ Describe the difference between build, unit, functional, install,
	+ integration, performance and acceptance tests.
	+
	+.. todo::
	+
	+ Describe continuous deployment
	+
	+.. todo::
	+
	+ Describe how to create a ticket
	+
	+.. todo::
	+
	+ Describe how to submit a patch
	+
	+.. todo::
	+
	+ Describe how to review and accept or decline a patch
	+
	+.. todo::
	+
	+ Describe how to formulate a feature request
	+
	+Kolab Groupware development largely follows an iterative and incremental
	+agile software development metholodogy also known as `Scrum`_.
	+
	+In summary, the Kolab Groupware development process is divided into
	+stages, with different teams participating in getting tasks to the next
	+stage of the process.
	+
	+Kolab Groupware is a collaboration suite consisting of many components,
	+each of them separate software development projects, some of them
	+dependent on third-party software development projects, and some of them
	+separate altogether. This creates some discrepancies in applying vanilla
	+Scrum practices to all projects in the Kolab universe.
	+
	+Furthermore, Kolab Groupware is a community software development
	+project, and not all participants in the community can be expected to be
	+familiar with (otherwise professional) software development processes.
	+
	+It is therefore that we document here how we work with `Scrum`_ using
	+`Phabricator`_.
	+
	+Benefits of Phabricator, Scrum and Test-Driven Development
	+==========================================================
	+
	+A plethora of benefits exist in using Phabricator and Scrum over the
	+current processes (which do not fall under any known nomenclature), and
	+Test-Driven Development (TDD).
	+
	+* The processes and facilities are focused on structured software
	+ development.
	+
	+* Software development stands in stark contrast with longer-term
	+ commitments such as support.
	+
	+* A developer is supposed to work on tomorrow's version of the
	+ software, and not yesterday's, as every distraction with yesterday's
	+ software stands in the way of the focus and dedication needed to
	+ provide tomorrow's innovative and competitive software.
	+
	+* And every distraction stands in the way of the personal and
	+ professional development of the individual developer.
	+
	+* We aim to pull product support away from software development.
	+
	+* A Bugzilla is not suitable for agile software development (even with
	+ tooling such as Scrumbugz), and the former point may have
	+ illustrated we wish software development to be agile.
	+
	+* Various factors in the world of IT as well as common software
	+ development practices predicate a shift toward continuous deployment
	+ (at one cost) over sometimes overly precautious long-term support
	+ methodologies (at another cost).
	+
	+* The dynamics of these costs work in favor of a level of agility in
	+ software development as well as operations, especially with smaller
	+ teams.
	+
	+Getting Acquainted with Phabricator
	+===================================
	+
	+We use `Projects`_ in `Phabricator`_ as a means to group people and
	+assign them roles, rights and responsibilities in a broader process.
	+
	+Tickets are created as `Maniphest`_ tasks, and roll on forward through
	+the process from thereon.
	+
	+Software Development Projects
	+-----------------------------
	+
	+The first type of project is a Software Development Project. These
	+are generally associated with one or more source code management
	+repositories.
	+
	+Each software development project is responsible for a single software
	+component included in Kolab Groupware, such as chwala or
	+pykolab.
	+
	+Because the Kolab community is an open community, membership to these
	+software development projects is open -- meaning registered users can
	+join and leave as they like.
	+
	+Authorization Groups (Developer Teams)
	+--------------------------------------
	+
	+Each software development project that operates source code management
	+repositories also has a group associated with it that is used for
	+authorization to push to the associated source code management
	+repositories.
	+
	+For the PyKolab software development project for example, a group
	+PyKolab Developers has access to push to the ``pykolab`` GIT
	+repository.
	+
	+These groups are mostly self-regulated, in that members of the group can
	+add other members to the group.
	+
	+Teams and Roles
	+---------------
	+
	+Teams and roles that are not software development teams include teams
	+such as `Product Owners`_, `Scrum Masters`_ and `Quality Assurance`_.
	+
	+Sprints
	+-------
	+
	+`Sprints`_ are what is in the name. They are a time-limited series of
	+events resulting in deliverables being emitted at the end of the sprint.
	+
	+This series of events consists of:
	+
	+Planning Meeting
	+
	+ Held at the beginning of each sprint, the `Product Owners`_ and the
	+ developer team negotiate which tasks on the Sprint's backlog they
	+ will attempt to complete.
	+
	+ The `Product Owners`_ determine the priority of tasks and declare
	+ which (of all tasks) render the most business value.
	+
	+ The development team determines the amount of work they feel they
	+ can achieve during the sprint without incurring technical debt.
	+
	+ .. NOTE::
	+
	+ The `Product Owners`_ use tasks related to individual software
	+ development projects and associate them with the next
	+ sprint in order to build an initial sprint backlog.
	+
	+ Working the other way around, where the team in collaboration
	+ with the `Product Owners`_ determine which tasks to put on the
	+ sprint backlog doesn't scale to the number of individual
	+ software development projects for Kolab Groupware as a whole.
	+
	+Daily Scrums
	+
	+ Short, daily stand-up meetings are used to let team members
	+ summarize yesterday's work, today's work and talk about any
	+ impediments encountered.
	+
	+ This ensures team members communicate early and often about their
	+ work, problems they find, and facilitate the fast exchange of
	+ knowledge and ideas or call for help.
	+
	+Review Meeting
	+
	+
	+
	+Retrospective Meeting
	+
	+Process Stages
	+==============
	+
	+The stages of the development process largely align with a manufacturing
	+process of, say, cars.
	+
	+.. _developer-guide-process-stage-concept:
	+
	+Concept
	+-------
	+
	+This stage is an almost completely iterative process; Ideas are
	+generated, possibly prototyped and thrown away on a regular basis.
	+
	+As such, concepts may or may not make it to production. In keeping with
	+the analogy of a car manufacturer, this may be a design drawing for a
	+new car (up to and including showing off a prototype on a trade show),
	+or some new technology (stage 2 artificial intelligence).
	+
	+For Kolab Groupware, this stage mostly involves research and
	+development not necessarily based on consumer input.
	+
	+The output of this process (if at all "valid") is additional input to
	+the next stage, :ref:`developer-guide-process-stage-pre-production`.
	+
	+.. _developer-guide-process-stage-pre-production:
	+
	+Pre-Production
	+--------------
	+
	+The pre-production stage is an interaction between consumers of the
	+product, `Product Owners`_, `Architecture & Design`_ and
	+`Quality Assurance`_.
	+
	+:ref:`developer-guide-process-roles-consumers` of the product request
	+features or report issues, that end up on the Product Backlog [#]_.
	+`Product Owners`_ prioritize these tasks.
	+
	+Depending on the complexity of the task, and with the existing need to
	+facilitate the smoothest possible execution of the Production phase,
	+`Product Owners`_ and `Scrum Masters`_ request a review to be aided by
	+the `Architecture & Design`_ and `Quality Assurance`_ teams.
	+
	+The input for this stage may be anything from UI elements with the wrong
	+teint (easy to forward to Production as-is) to complex enhancements
	+to Kolab Groupware as a whole, requiring design and possibly touching
	+the codebase of multiple software projects (such as the implementation
	+of Federated Central Authentication Services with Two-Factor
	+Authentication support).
	+
	+Regardless, the effort at this stage involves breaking down tasks in to
	+digestible sub-tasks ready for Production.
	+
	+Production
	+----------
	+
	+Production is the stage where development work takes place. The form in
	+which is this happens is through `Sprints`_, which are limited chunks of
	+time in which several events take place that shape the development
	+process for :ref:`developer-guide-process-roles-developers`.
	+
	+The input for this stage has initially been composed during the previous
	+sprint, with `Product Owners`_ putting tasks from dozens of software
	+development project backlogs on to the backlog for the current sprint.
	+
	+Note that at this point, most facets of tasks have already been
	+negotiated -- but only to a certain extent.
	+
	+If a relatively small task involves changes in one software project
	+dependent on changes in another software project, then this should have
	+been settled either before the individual sub-tasks end up on the sprint
	+backlog, or happens during the sprint planning meeting.
	+
	+Post-Production
	+---------------
	+
	+Roles
	+=====
	+
	+.. _developer-guide-process-roles-stakeholders:
	+
	+Stakeholders
	+------------
	+
	+Stakeholders are parties interested in the product, and are responsible
	+for the creation of feature implementation requests, bug reports and
	+acceptance testing.
	+
	+As such, stakeholders include customers (of Kolab Systems and its
	+partners), but actually include all consumers of Kolab. In other words,
	+regardless of affiliation or status, while you are reading this you
	+are probably a stakeholder.
	+
	+However, some stakeholders' wishes have more weight than others. This
	+is likely reflected (at most) in the priority of the task(s) at hand,
	+which dictates the order in which tasks are worked on.
	+
	+.. _developer-guide-process-role-product-owner:
	+
	+Product Owner
	+-------------
	+
	+The role of a product owner (usually a singular entity) is to determine
	+the value of goals (set out as epics and tasks in `Maniphest`_) and
	+prioritize the associated epics and tasks accordingly.
	+
	+When the product owner does so, he or she determines the value of goals
	+on behalf of the stakeholders, and in light of an overall vision on
	+where the product should go.
	+
	+Within the Kolab Groupware universe, where the product is the Kolab
	+release, and dozens of individual software development projects make up
	+the product, several aspects make the `Product Owners`_ a team of
	+individuals rather than a single person:
	+
	+* Not all software development projects are related to the product.
	+
	+ Such may include work on Phabricator or the Sprint extension to
	+ Phabricator (i.e. facilitatory third-party software).
	+
	+* Not all software development projects are under the control of the
	+ business.
	+
	+ This may include third-party software development projects we
	+ contribute to (i.e. Roundcube).
	+
	+However in the context of `Scrum`_ and particularly the `Sprints`_,
	+there is only one stakeholder representative -- the Product Owner.
	+
	+.. _developer-guide-process-roles-scrum-masters:
	+
	+Scrum Masters
	+-------------
	+
	+`Scrum Masters`_ facilitate the Scrum process ...
	+
	+.. rubric:: Checklist for the Beginning and End of a Sprint
	+
	+#. Remove the hash-tag `sprint_server_current` from the past sprint,
	+#. Remove the hash-tag `sprint_server_next` from the current sprint,
	+#. Add the hash-tag `sprint_server_current` to the current sprint,
	+#. Create a new sprint,
	+#. Set the start and end dates for the new sprint,
	+#. Add the hash-tag `sprint_server_next` to the next sprint.
	+
	+.. _developer-guide-process-roles-architecture-and-design:
	+
	+Architecture & Design
	+---------------------
	+
	+.. _developer-guide-process-roles-quality-assurance:
	+
	+Quality Assurance
	+-----------------
	+
	+.. _developer-guide-process-roles-developers:
	+
	+Developers
	+----------
	+
	+.. _developer-guide-process-roles-consumers:
	+
	+Consumers
	+---------
	+
	+* A user or customer requests the resolution of a certain issue.
	+
	+* The product owner(s)
	+
	+Continuous Integration, Delivery & Deployment
	+=============================================
	+
	+.. graphviz::
	+
	+ digraph {
	+ rankdir = LR;
	+ splines = true;
	+ overlab = prism;
	+
	+ edge [color=gray50, fontname=Calibri, fontsize=11];
	+ node [shape=record, fontname=Calibri, fontsize=11];
	+
	+ "contributor" -> "Phabricator";
	+
	+ "Phabricator" -> "Build Host";
	+
	+ "Build Host" -> "Docker Container(s)";
	+
	+ }
	+
	+#. A contributor contributes code via `Differential`_ to create or
	+ update a code review proposal, or `Diffusion`_ to commit directly
	+ to the GIT repository for the Software Development Project.
	+
	+#. `Herald`_, the `Phabricator`_ rule engine, is used to trigger the
	+ execution of a `Harbormaster`_ build plan [#]_.
	+
	+#. `Harbormaster`_ allocates a `Drydock`_ host to execute a script on.
	+
	+#. The `Drydock`_ host's script is supplied with the repository and
	+ the commit in question.
	+
	+#. The `Drydock`_ hosts used are `Atomic`_ hosts, meaning they run
	+ `Docker`_ containers to execute Continuous Integration.
	+
	+#. The so-called entrypoint for the Docker images (executed when a
	+ container is started from the image) is designed to execute
	+ Continuous Integration and Continuous Delivery.
	+
	+Continuous Integration
	+----------------------
	+
	+Continuous Integration is performed using the following stages;
	+
	+* A build stage in which the software build dependencies are
	+ installed in to the Docker container, and the software is built.
	+
	+ In the case of software that does not need to be compiled, such as
	+ PHP and/or JavaScript, the build stage executes syntax checks.
	+
	+* A unit testing stage, which is limited to testing individual
	+ functions of the software, such as ``sum(a, b)`` with ``a=1; b=2``
	+ indeed resulting in ``3``, but also does not yield unexpected
	+ behaviour:
	+
	+ * ``sum(a, b)`` over ``a=1`` correctly raises an argument
	+ exception (if expected to), or returns ``1`` (if expected to),
	+
	+ * ``sum(a, b)`` over ``a="Hello"`` and ``b="world!"``;
	+
	+ * does not unintentionally result in ``"Hello world!"`` nor
	+ ``"Helloworld!"``,
	+
	+ * raises the correct exception, or returns false, none or the
	+ equivalent of ``NaN``,
	+
	+ * ``sum(a, b)`` over ``a=1; b="apple"`` does not result in ``1``
	+ (unless expected) and raises the correct exception (if expected
	+ to).
	+
	+ * etcetera, etcetera.
	+
	+ Unit testing further includes testing if underlying software
	+ behaves in a way that the software can handle correctly. This may
	+ include tests that determine whether stripping invalid characters
	+ from a string (by iconv) yields the expected result, and
	+ whether the version of the API provided by underlying software is
	+ sufficient.
	+
	+ .. NOTE::
	+
	+ In cases where function calls require infrastructure (such as a
	+ SQL server) with :term:`fixtures`, unit tests have to replace
	+ the code that would interact with the infrastructure with code
	+ that returns data as if the infrastructure existed. This is
	+ called mocking up.
	+
	+ Tests that do indeed require infrastructure, and/or cannot be
	+ mocked up, are called functional tests.
	+
	+* A functional testing stage, in which functions of the software
	+ are tested which require a minimal amount of infrastructure.
	+
	+ This may include functions that imply a caching layer such as
	+ memcached is available (populating a cache with fixtures,
	+ marking it as dirty, and expecting retrieval to return no data).
	+
	+ .. NOTE::
	+
	+ It should be noted that the distinction between unit and
	+ functional testing is largely a matter of job control.
	+
	+ It should also be noted that functional tests are executed
	+ against a minimal infrastructure -- the keyword being
	+ minimal. This usually precludes infrastructure needed to
	+ authenticate users, and usually precludes testing functions
	+ against various implementations of a piece of functionality
	+ (such as an IMAP server needed by Roundcube testing possibly
	+ being either of UW-IMAP, Courier, Cyrus IMAP, Dovecot, ...).
	+
	+* A packaging stage, in which the software is packaged up for
	+ distribution.
	+
	+* An installation testing stage, in which the result of the
	+ packaging is installed.
	+
	+* An upgrade testing stage, in which any number of former release's
	+ fixtures are put in place, and the upgrade path is supposed to be
	+ completed successfully automatically (such as a
	+ :command:`rake db:migrate`).
	+
	+* An integration testing stage
	+
	+* An acceptance testing stage, in which human beings experience
	+ the implementation.
	+
	+Continuous Delivery
	+-------------------
	+
	+.. _developer-guide-using-arcanist:
	+
	+Using Arcanist
	+==============
	+
	+.. rubric:: Footnotes
	+
	+.. [#]
	+
	+ Kolab Groupware consists of dozens of individual product backlogs.
	+
	+.. [#]
	+
	+ The sources for this script live in the Stick repository at
	+ `drydocker.sh`_.
	+
	+.. _Scrum: http://en.wikipedia.org/wiki/Scrum_%28software_development%29
	+.. _drydocker.sh: https://git.kolab.org/diffusion/QA/browse/master/drydocker.sh
	diff --git a/source/index.rst b/source/index.rst
	--- a/source/index.rst
	+++ b/source/index.rst
	@@ -14,6 +14,13 @@

	Read more in our :ref:`introduction`.

	+.. rubric:: The Currency of Kudo is Beer
	+
	+.. toctree::
	+ :maxdepth: 1
	+
	+ contributor-guide/index
	+
	.. rubric:: Planning Your Kolab Groupware Deployment

	.. toctree::

File Metadata

Mime Type: text/plain
Expires: Sat, Apr 4, 8:06 AM (3 d, 10 h ago)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 18828614
Default Alt Text: D89.1775289989.diff (57 KB)

D89.1775289989.diffNo OneTemporaryActions

D89.1775289989.diffView Options

File Metadata

Event Timeline

D89.1775289989.diff
No OneTemporary
Actions

D89.1775289989.diff
View Options