Permalink
Browse files

Common sense Amendment Bylaw

This clarifies a general unwritten rule, with some obvious exceptions, looking forward to a day when
we have to deprecate and replace PSRs. Typos are already being merged as are formatting issues, so none of this should be considered new or scary.

The only major difference is "reference areas", which make ONE AND ONLY ONE part of PSRs variable, and that is PURELY to allow PSRs to be pushed onto the stack of dependencies IF THEY ARE DEEMED COMPATIBLE. Incompatible PSRs are obviously not going to be listed in a list of compatible PSRs.
  • Loading branch information...
1 parent 1b4f98e commit 0da2fc792762b33d56f70d2efe7c7c1c0d4f3e07 Phil Sturgeon committed Jan 12, 2014
View
3 accepted/PSR-1-basic-coding-standard.md
@@ -11,6 +11,7 @@ interpreted as described in [RFC 2119][].
[RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt
[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
+[PSR-4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md
1. Overview
@@ -24,7 +25,7 @@ interpreted as described in [RFC 2119][].
*or* cause side-effects (e.g. generate output, change .ini settings, etc.)
but SHOULD NOT do both.
-- Namespaces and classes MUST follow [PSR-0][].
+- Namespaces and classes MUST follow an "autoloading" PSR: [[PSR-0][], [PSR-4][]].
- Class names MUST be declared in `StudlyCaps`.
View
2 accepted/PSR-2-coding-style-guide.md
@@ -25,7 +25,7 @@ interpreted as described in [RFC 2119][].
1. Overview
-----------
-- Code MUST follow [PSR-1][].
+- Code MUST follow a "coding style guide" PSR [[PSR-1][]].
- Code MUST use 4 spaces for indenting, not tabs.
View
2 bylaws/002-psr-naming-conventions.md
@@ -1,5 +1,5 @@
Naming conventions for code released by PHP-FIG
------------------------------------------------
+===============================================
1. Interfaces MUST be suffixed by `Interface`: e.g. `Psr\Foo\BarInterface`.
2. Abstract classes MUST be prefixed by `Abstract`: e.g. `Psr\Foo\AbstractBar`.
View
3 bylaws/004-psr-workflow.md
@@ -1,4 +1,5 @@
-# PSR Review Workflow
+PSR Review Workflow
+===================
This document describes the workflow for proposing a PSR and having it published by the PHP-FIG.
View
3 bylaws/005-licensing-policies.md
@@ -1,4 +1,5 @@
-# Licensing Policies
+Licensing Policies
+==================
## 1. Code
View
80 bylaws/006-psr-amendments.md
@@ -0,0 +1,80 @@
+Amendments
+==========
+
+Following the rules of the [workflow bylaw][], once a PSR has been "Accepted" the PSR meaning
+cannot change, backwards compatibility MUST remain at 100%, and any confusion that arises from
+original wording MAY be clarified through errata.
+
+The rules for errata are covered in the [workflow bylaw][], and only allow non-backwards compatible clarification to be added to the meta document. Sometimes, modifications will be necessary in PSR document itself, and this document outlines those cases.
+
+## 1. Deprecation and Replacement
+
+If a PSR is found to require substantive updates or errata is no longer serves as a
+useful resource to clarify confusion, then the PSR must be replaced, following
+the workflow set out in [workflow bylaw][].
+
+The original PSR may at some point in time be deprecated, and the new PSR becomes the recommended
+document. Deprecation and recommendation changes must be made with a vote according to the rules
+of the [voting protocol][], with a subject like "[VOTE] Deprecate PSR-X", at which point a PSR-Y should be specified as a recommendation.
+
+Once a vote has passed with the decision to deprecate a PSR and supersede it
+with another PSR, the deprecated PSR must be marked as such in the original
+document and a link should be placed in the body.
+
+For example:
+
+> **Deprecated** - As of 01/01/2014 PSR-0 has been marked as deprecated. PSR-4 is now recommended
+as an alternative.
+
+
+## 2. Dependencies
+
+As documents are expected to be replaced rather than amended, dependencies on
+other PSR's should be avoided whenever possible. For instance, the follow is
+no longer permitted:
+
+> - Namespaces and classes MUST follow PSR-0.
+
+Instead the following example must be used:
+
+> - Namespaces and classes MUST follow an autoloading PSR: [PSR-0].
+
+These square brackets denote a "reference area", which is a list of PSRs that
+conform to the rule. These may ONLY be added to, and never removed.
+
+> - Namespaces and classes MUST follow an autoloading PSR: [PSR-0, PSR-4].
+
+As new PSRs are created which satisfy a requirement, they may be added. Even if
+adding a new PSR involves deprecating another PSR, that deprecated PSR will
+remain in the document, as anything else would break backwards compatibility.
+
+## 3. Acceptable Amendments
+
+Other than the updating of dependency references, there are two other potentially
+acceptable amendment scenarios which do not require their own special vote.
+
+### 3.1. Annotations
+
+If Errata is added which is deemed important enough by whoever is initiating the errata vote,
+annotations may be placed in or near the offending line so that readers know to view the errata for
+more information.
+
+> - Something confusing about where brackets go. [cf. [errata](foo-meta.md#anchor)]
+
+This will be done as part of the errata vote, not its own.
+
+### 3.2. Formatting & Typos
+
+If formatting is broken for any reason then changing formatting must not be considered a
+change to the document. These can be merged or pushed without hesitation, as long as they
+don't change anything of any meaning or syntax. Common sense will help here.
+
+Examples:
+
+1. HTML Tables are currently broken on php-fig.org because of the syntax used.
+2. Somebody spelled something wrong and nobody spotted it for a year.
+3. Problems with GitHub Markdown
+
+
+[workflow bylaw]: https://github.com/philsturgeon/fig-standards/blob/master/bylaws/004-psr-workflow.md
+[voting protocol]: https://github.com/philsturgeon/fig-standards/blob/master/bylaws/001-voting-protocol.md

0 comments on commit 0da2fc7

Please sign in to comment.