Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Implemented Pádraic Brady's Feedback

  • Loading branch information...
commit 50cf2832e9e1135254f1bf5b181a909fbd81638b 1 parent 17e6b90
@philsturgeon philsturgeon authored
Showing with 35 additions and 28 deletions.
  1. +35 −28 bylaws/006-psr-amendments.md
View
63 bylaws/006-psr-amendments.md
@@ -2,64 +2,69 @@ 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.
+cannot change, backwards compatibility must remain at 100%, and any confusion that arises from
+original wording can 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.
+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].
+If a PSR is found to require substantive updates or errata is no longer able 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.
+of the [voting protocol], with a subject like "[VOTE] Deprecate PSR-X", at which point a
+superseding PSR 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.
+Once a vote has passed 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:
+For example, the following Markdown be placed at the very top of the relevant standard file in the
+official PHP-FIG GitHub repo `fig-standards`.
-> **Deprecated** - As of 01/01/2014 PSR-0 has been marked as deprecated. PSR-4 is now recommended
+> **Deprecated** - As of 2014-12-30 PSR-0 has been marked as deprecated. [PSR-4] is now recommended
as an alternative.
+> [PSR-4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md
-## 2. Dependencies
+## 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
+other PSR's should be avoided whenever possible. For instance, the following is
no longer permitted:
> - Namespaces and classes MUST follow PSR-0.
-Instead the following example must be used:
+Instead - if a dependency is considered necessary by the working group creating it - then the following
+example can be used:
-> - Namespaces and classes MUST follow an autoloading PSR: [PSR-0].
+> - 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.
+The outer set of square brackets denote a "dependency list", which is a list of PSRs
+that are considered a compatible dependency.
-> - Namespaces and classes MUST follow an autoloading PSR: [PSR-0, PSR-4].
+When more PSR's are added to the "dependency list" the same example would look like this:
-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.
+> - Namespaces and classes MUST follow an autoloading PSR: [ [PSR-0], [PSR-4] ].
+
+New PSR's can be added to the "dependency list", but old PSR's can never be removed as this would break
+backwards compatability.
## 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.
+Other than updating the "dependency list", 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.
+more information, with a link containing an anchor to that specific piece of errata.
-> - Something confusing about where brackets go. [cf. [errata](foo-meta.md#anchor)]
+> - Something confusing about where brackets go. [cf. [errata](foo-meta.md#errata-1-foo)]
This will be done as part of the errata vote, not its own.
@@ -67,7 +72,10 @@ This will be done as part of the errata vote, not its own.
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.
+don't change anything of any meaning or syntax.
+
+Some typos as trivial as a misplaced comma could have a subtle impact on meaning. Take special care not to
+alter backwards compatibility and create a vote if unsure. Common sense will help here.
Examples:
@@ -75,6 +83,5 @@ Examples:
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
Please sign in to comment.
Something went wrong with that request. Please try again.