Add migration document re differences between PER-CS v1.0 and PER-CS v2.0#82
Conversation
Jean85
left a comment
There was a problem hiding this comment.
Is there a reason why we're not highlighting that PER-CS 1.0 is basically the same as PSR-12? That would streamline the process, and make the progression toward new PER-CS versions clearer in terms of changelog.
Also, we already have a rough changelog in the release page: https://github.com/php-fig/per-coding-style/releases/tag/2.0.0
Do we want to change it? Or to take that list in any way and put it here?
|
I've added a link to that auto-generated changelog now. The aim of this document is to lower the barrier for tool authors so they can create action lists of what they need to do to support PER-CS v2.0. Consider it our equivalent of the migration documents such as https://www.php.net/manual/en/migration81.php, https://www.php.net/manual/en/migration83.php etc - we don't assume or direct people to just look at the changelogs for the new versions of PHP so I think it would be similarly polite that we provide the same for PER-CS. With that in mind, perhaps I should have called this a "migration file". |
We can make the content for the release whatever we want, it doesn't need to be various commit messages or a diff. |
Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
|
I am still torn on whether we should include as much detail for the new sections. What's the value of providing more text to read beyond "there's a new section on arrays. Go read it." Literally every word in a new section is something an implementer needs to care about, so the summary is essentially redundant with the spec. |
|
@Crell could be turned into a blog post if we don't want it in meta-doc. But I think such meta-doc is useful to increase adoption. |
|
@samdark I've tightened things up as you suggested. |
Co-authored-by: Korvin Szanto <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Korvin Szanto <[email protected]> Co-authored-by: Alexander Makarov <[email protected]>
Co-authored-by: Alexander Makarov <[email protected]>
|
Updated as requested by @Crell earlier today... |
|
Can you update the code blocks to be 3 backticks rather than indented by 4 spaces and remove the closing tags? enables PHP syntax highlighting work. See examples from the spec: https://github.com/php-fig/per-coding-style/blob/master/spec.md?plain=1#L266-L275 |
There is now at least one example per section
There is now at least one example per section
When discussing differences between PSR-12 and PER-CS it is useful to have a summarised document detailing those changes.
This document is provided for that reason, and should be possible to use it to derive action lists for the likes of phpcs etc.
The scope of this document is to solely describe changes between the two aforementioned specs (PSR-12 and PER-CS v2.0), when required a new document would describe changes between PER-CS v2.0 and the next version - much in the same way that there are "Migration Documents" for PHP from one version to the next version. (We don't direct people to just look at the changelog files for PHP, instead migration documents are handwritten...)
It is intended that authors of tools such as PHP CodeSniffer and PHP CS Fixer would use this document(s) to drive their action lists so they can fully support each PER-CS iteration without having to investigate the minutiae.