Skip to content

Commit

Permalink
Documented Project Management and removed QA process
Browse files Browse the repository at this point in the history
During SymfonyCon 2019 Jaap and I met and discussed how to work with
Github, and specifically projects. I decided to write a draft on how we
want to do project management for phpDocumentor so that it is clear for
new contributors, ourselves and possibly our users how we deal with
incoming requests, issues but also our roadmap.

I would like to stress that this is a draft that I would like to have
reviewed by the other team members.

As a sidenote, I also deleted the QA document from the internals folder
because it was heavily outdated. A new document needs to be written in
its place but that it out of scope for this change.
  • Loading branch information
mvriel committed Nov 23, 2019
1 parent f0bd4e4 commit 2fa385f
Show file tree
Hide file tree
Showing 3 changed files with 82 additions and 32 deletions.
2 changes: 1 addition & 1 deletion docs/internals/index.rst
Expand Up @@ -4,7 +4,7 @@ Internals
.. toctree::
:maxdepth: 2

qa.rst
project-management
flow
contructing-the-ast
tags
Expand Down
81 changes: 81 additions & 0 deletions docs/internals/project-management.rst
@@ -0,0 +1,81 @@
Project Management
==================

.. note:: This documentation is about hwo the phpDocumentor team is organized and how it determines priorities and which
tooling to use. When you are a user of phpDocumentor you can safely ignore this piece of documentation.

.. note:: As with many open source projects, the phpDocumentor team consists of a very small number of core contributors
who do this in their spare time. This may mean that even if an issue is urgent or able to be quickly responded
to; it could still take some time because of availability.

Release schedule
----------------

While writing this document, the team has no set release schedule as it is focusing on getting phpDocumentor 3 released.
This version includes significant architectural changes; meaning that it is highly unpredictable when it can be
released. As soon as phpDocumentor 3 is released, the team can review and change how they can setup a release schedule.

Workflows
---------

To manage the phpDocumentor project we distinguish between three different workflows:

1. Responding to issues
2. Pull requests
3. Planning and developing of new features

Responding to issues
~~~~~~~~~~~~~~~~~~~~

The phpDocumentor team reviews any incoming issue and performs a form of triage; in this phase the urgency of the issue
is determined and what type of issue this is. We distinguish between bugs, enhancements, research and documentation
issues. During triage an issue is labelled with one of these labels to indicate its type.

When the issue is a question, can be dealt with swiftly or is deemed urgent enough a team member will respond to the
issue as soon as we can.

Issues should preferably be assigned to a milestone; the absence of this may indicate an issue is not planned for
inclusion in a known, upcoming, release. A team member may create a new milestone when deemed necessary and assign
issues there when they consider it for resolving at that time.

When an issue is related to a project, or epic, that is in development. The issue may be assigned to that respective
Github project; see `Planning and developing of new features`_ for more information on the use of Github Projects.

Pull requests
~~~~~~~~~~~~~

When a pull request comes in this is considered an urgent activity that should be responded to as quickly as
availability allows.

Please refer to the CONTRIBUTING.md in the root of this project for what we expect from a pull request. When a pull
request does not match this criteria it is vital to be as helpful as an be and guide the issuer on how to help us get
the pull request included.

There are times when the content of a pull request does not match the strategy or intended architecture of
phpDocumentor. In these cases it may happen that the team is not able to accept a contribution. This does not mean a
pull request is bad or we do not appreciate the time that the issuer has spent; sometimes some things do not fit into
the whole or have an, unforeseeable, adverse impact elsewhere.

Planning and developing of new features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For larger efforts, those that do not fit into one issue, we make a `Github Project on the organisational level`_.
This project represents an epic or otherwise significant effort that we need to keep track of. This does not include
the release of new versions of phpDocumentor as these are tracked using milestones.

.. note: The intended difference in use between milestones and projects is that a project does not need to be completed
withing the span of one release; by distinguishing between milestones/releases and projects/epics we are able
to do so.
Since a larger effort may span one or more repositories that we consume, a project on the organisational level is
preferred. Projects on a repository level are discouraged and should either be closed as soon as possible or migrated
to a organisational level.

This is also done so that there is always a clear list of priorities and that the team is able to view all on-going
projects/epics.

As a preference, projects should be made public so that the community can also benefit from this and view what the team
is working on. Private projects are allowed for various reasons, for example: unannounced experimental features or
proof of concepts.

.. _Github Project on the organisational level: https://github.com/orgs/phpDocumentor/projects
31 changes: 0 additions & 31 deletions docs/internals/qa.rst

This file was deleted.

0 comments on commit 2fa385f

Please sign in to comment.