Amendment Bylaw #247

Merged
merged 13 commits into from Mar 1, 2014

Conversation

Projects
None yet
4 participants
Contributor

philsturgeon commented Jan 12, 2014

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.

@samdark samdark commented on an outdated diff Jan 12, 2014

bylaws/006-psr-amendments.md
@@ -0,0 +1,63 @@
+Amendments
+==========
+
+Once a PSR has been "Accepted", the PSR meaning cannot change, backwards
+compatibility will remain at 100%, and any confusion that arises from original
+wording may only be clarified through Errata - as outlined in
+`bylaws/004-psr-workflow.md`.
+
+If a PSR is found to require updates or errata is no longer server as a
@samdark

samdark Jan 12, 2014

Contributor

server → serves?

@samdark samdark commented on an outdated diff Jan 12, 2014

bylaws/006-psr-amendments.md
@@ -0,0 +1,63 @@
+Amendments
+==========
+
+Once a PSR has been "Accepted", the PSR meaning cannot change, backwards
+compatibility will remain at 100%, and any confusion that arises from original
+wording may only be clarified through Errata - as outlined in
+`bylaws/004-psr-workflow.md`.
+
+If a PSR is found to require updates or errata is no longer server as a
+useful resource to clarify confusion, then the PSR must be replaced, following
+the workflow set out in `bylaws/004-psr-workflow.md`.
@samdark

samdark Jan 12, 2014

Contributor

bylaws/004-psr-workflow.md should be link instead of code.

@samdark samdark commented on an outdated diff Jan 12, 2014

bylaws/006-psr-amendments.md
@@ -0,0 +1,63 @@
+Amendments
+==========
+
+Once a PSR has been "Accepted", the PSR meaning cannot change, backwards
+compatibility will remain at 100%, and any confusion that arises from original
+wording may only be clarified through Errata - as outlined in
+`bylaws/004-psr-workflow.md`.
@samdark

samdark Jan 12, 2014

Contributor

bylaws/004-psr-workflow.md should be link instead of code.

@samdark samdark commented on an outdated diff Jan 12, 2014

bylaws/006-psr-amendments.md
+A vote has been won with the decision to deprecate a PSR and superceed 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. Annotations
+
+If Errata is added which is deemed important enough, annotations may be placed in
+or near the offending line so that readers know to view the errata for more
+information.
+
+> - Something something confusing about where brackets go. [cf. [errata](foo-meta.md#anchor)]
@samdark

samdark Jan 12, 2014

Contributor

Something something → Something?

Phil Sturgeon added some commits Jan 12, 2014

@alias-mac alias-mac and 1 other commented on an outdated diff Jan 15, 2014

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][]].
@alias-mac

alias-mac Jan 15, 2014

@philsturgeon, I don't want to be picky, but could this be interpreted as any coding style that might exist and just be a mix?

I mean, imagine that we will have a PSR-10 for new code style or improved one, this would say that we can follow a bit of both even if they aren't compatible? This basically goes for that obsolete/deprecated PSRs that we might have moving forward.

@philsturgeon

philsturgeon Jan 15, 2014

Contributor

If they arent compatible they wouldn't be added to the list. ;)

Obsolete/deprecated PSRs must always remain in the list. If the user wants to ignore the deprecation warning and use it anyway then... well yay for them.

In 5 years time some muppet will use PSR-0 because they have to write PHP 5.2 code. We won't ever stop people from doing that.

@alias-mac alias-mac and 1 other commented on an outdated diff Jan 15, 2014

bylaws/006-psr-amendments.md
@@ -0,0 +1,63 @@
+Amendments
+==========
+
+Once a PSR has been "Accepted", the PSR meaning cannot change, backwards
+compatibility will remain at 100%, and any confusion that arises from original
+wording may only be clarified through Errata - as outlined in
+`bylaws/004-psr-workflow.md`.
+
+If a PSR is found to require 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 `bylaws/004-psr-workflow.md`.
@alias-mac

alias-mac Jan 15, 2014

shouldn't it be a link?

@philsturgeon

philsturgeon Jan 15, 2014

Contributor

You and @samdark make a cute couple.

screen shot 2014-01-15 at 11 30 58

Links to Markdown files dont work very well. I think this is fine. I might even just make it text.

@philsturgeon

philsturgeon Jan 16, 2014

Contributor

I was continuing what PSR-1 was already doing, obviously im not going to change it unnecessarily, but Im not too fused about doing this for bylaws.

@alias-mac alias-mac and 1 other commented on an outdated diff Jan 15, 2014

bylaws/006-psr-amendments.md
+
+## 2. Acceptable Amendments
+
+Other than the updating of dependency references, there are two other potentialy
+acceptable amendment scenarios.
+
+### 1. Deprecation and Replacement
+
+A vote has been won with the decision to deprecate a PSR and superceed 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.
@alias-mac

alias-mac Jan 15, 2014

I don't think we should put dates etc, imho should be only a link to the new PSR that replaces this one, but this is just an example and we can decide that later on how they should look like (based on the group discussion already running).

@philsturgeon

philsturgeon Jan 15, 2014

Contributor

I see no downside to seeing when something was marked as deprecated.

As you say: Yes this is just an example, yes it can change.

@alias-mac alias-mac commented on an outdated diff Jan 15, 2014

bylaws/006-psr-amendments.md
+
+If a PSR is found to require 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 `bylaws/004-psr-workflow.md`.
+
+The original PSR may then be deprecated, and the new PSR becomes the recommended
+document.
+
+## 1. Dependencies
+
+As documents are expected to be replaced rather than amended, dependencies on
+other PSR's should be avoided whenever possbible. For instance:
+
+> - Namespaces and classes MUST follow PSR-0.
+
+This is no longer allowed.
@alias-mac

alias-mac Jan 15, 2014

This actually looks like a statement for the next example instead of the above.
Probably we should change it to:

We no longer allow hard coded dependencies like:

  • Namespaces and classes MUST follow PSR-0.

Although a "reference area" ... like:

  • Namespaces and classes MUST follow an autoloading PSR: [PSR-0].

@alias-mac alias-mac commented on an outdated diff Jan 15, 2014

bylaws/006-psr-amendments.md
+
+## 1. Dependencies
+
+As documents are expected to be replaced rather than amended, dependencies on
+other PSR's should be avoided whenever possbible. For instance:
+
+> - Namespaces and classes MUST follow PSR-0.
+
+This is no longer allowed.
+
+> - 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].
@alias-mac

alias-mac Jan 15, 2014

gave my opinion about this in the group discussion about adding PSRs to reference areas.

Phil Sturgeon 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.
0da2fc7

@webmozart webmozart commented on an outdated diff Feb 11, 2014

accepted/PSR-1-basic-coding-standard.md
@@ -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][]].
@webmozart

webmozart Feb 11, 2014

Contributor

You don't need the trailing brackets [] in Markdown for referencing links. [PSR-0] etc. should work fine.

webmozart and others added some commits Feb 11, 2014

@webmozart webmozart Removed superfluous brackets 1f3aa6a
@webmozart webmozart Removed superfluous brackets ff2dd37
@webmozart webmozart Removed superfluous brackets 2771eed
Phil Sturgeon Merge pull request #3 from webmozart/patch-1
Removed superfluous brackets
c8fa379
Phil Sturgeon Merge branch 'amendments' of github.com:philsturgeon/fig-standards in…
…to amendments

Conflicts:
	accepted/PSR-1-basic-coding-standard.md
	accepted/PSR-2-coding-style-guide.md
	bylaws/006-psr-amendments.md
17e6b90
Phil Sturgeon Implemented Pádraic Brady's Feedback 50cf283

philsturgeon merged commit 2d009a3 into php-fig:master Mar 1, 2014

philsturgeon deleted the unknown repository branch Mar 1, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment