Ditch readme.txt in favour of readme.md

[anon66243189]

IMO since we expect Plugins and Themes to be GitHub hosted, we should think about abandoning the requirements for the readme.txt file.

Not only it is a major pain to switch between .md and .txt, with different formats and markups, but. mainly, I constantly forget to update either of them, resulting in a silly PR after PR just to update the missed one.

I saw a discussion here that talked about the update process and what filer to read:

Read description from readme.txt or readme.md

The download automatically updates when a new version is released; it would be good for the Description to also update to avoid different versions of the truth.

It never got a decision I think, and I would like to petition this, so we can collectively decide on what to do.

If there are no technical concerns I vote for ditching the dinosaur in favour of the more modern chicken (chickens are descendants of dinosaurs)
In other words, expect and support a readme.md, and do not expect or read a readme.txt

Perhaps I miss something, but I think it is a classic case of non-DRY approach to have both.
It will likely require some changes down the road for the Plugin Details displaying in the CP Plugins Admin list, but since we do not have our own API for that yet anyway I think it is a good moment to think about that.

[azurecurve]

There has been a discussion around allowing only md while maintaining txt for backward compatibility.

I think there is an intention that this be enacted.

[viktor]

I think this would be a good idea. Maybe offer some sort of a converter for WP’s readme.txt file to MD.

[wadestriebel]

I am in favour of using the README.md

Some other discussions re this:

• Add a link to docs page
• Plugin card description length
• Plugins whose authors do not update them, should be removed

[joyously]

I thought Petitions were only for changes to the core software.
But core does not use the readme file. The readme is only for the API: either WP repository or CP directory.

[anon66243189]

I am not a fan of democracy, but if we are calling ourselves a democracy, then I see no better almost ideal example of democracy worldwide than the Helvetic Confederation’s Democracy.
Thus, I suggest reading up the definition of Petitions they have https://www.ch.ch/en/demokratie/political-rights/petition/.
It is very similar to WikiPedia’s definition, and several dictionaries.

A petition is neither a binding people act (that would be a referendum), it has no legal implications, and the governing force could simply ignore it.
It can be about any state or all-day matter.

Thus, if we want to change or implement something that affects a lot of people or an entire community then a petition is sort of the place to start in CP, I think.

If you where to want to change how petitions work, you’d have to start with a petition. Technically, even implementing a DOC could have discussed first in a petition. Not sure thou that would have made sense, because it did not break anything, and was a generally agreed upon necessity, almost like no one will petition a permission to bring food for free to a catastrophe-hit area.

However changing the requirements of a readme file is a breaking change for many themes and plugins, and thus should be A) Discussed and B) At least based on some opinions and votes, and not on a single mind’s decision.

Just MO. The thread can be moved if inadequate in place. But I think it is spot on place.

If the topic requires more discussion, I suggest opening another, separated and targeted thread about Petitions purpose, goal and meaning in CP.

[viktor]

For reference, Governance page describes what petitions are for:

Petitions don’t have to be limited to changes to the ClassicPress code itself, either. This way, any person who senses a problem or opportunity can step up and initiate a process by which a topic can be discussed and the organization’s collective intelligence can be leveraged to assist in coming to a decision on the best path forward.

Let’s keep this thread limited to the topic at hand: replace readme.txt with readme.md.

[joyously]

@anon66243189

I think it is a classic case of non-DRY approach to have both

I agree with this, but no one ever dictated that you should have both.
Since the file is for the use of the API, the only other consideration is about imposing more work on authors that support both WP and CP.

[Simone]

At now the readme.txt (that you can include or not in GitHub) is served by Update Manager, so you can keep it on the CPT of the server.
It’s parsed and divided into sections by an API and then assembled in tabs when you click on “view more” link in plugin page.

I like very much how CodePotent plugins use both files in a different way:

• readme.txt to keep general info, screenshots titles, changelog…
• README.md to keep detailed instructions, filters documentation…

[anon71687268]

IIRC, there was discussion about this that aimed to keep both files. The readme.txt file was not ditched because doing so would mean devs have to maintain two versions of the same plugin if they want to also have it in the WP plugin repo. At this point (and probably for a least a couple more years,) it’s not a viable model to only put a plugin in the CP directory and not also put it in the WP repo to take advantage of the daily traffic and millions of eyes looking at the WP repo. I tried that. It didn’t work. It should be noted, as well, that at least some users have found ClassicPress by way of a note or blurb parsed from the readme.txt file of a plugin hosted at the WP repo.

[anon66243189]

I think you convinced me to agree on keeping both

[james]

@azurecurve

allowing only md while maintaining txt for backward compatibility

+1 from me.

It’s worth thinking through the various fields that could have conflicting information when both README.md and readme.txt are present, and how that should be handled. As stated earlier in this thread, having both files would be useful for plugins that are published in both the WP and CP directories.

[luizbills]

IMO I think we shouldn’t make the same WordPress mistakes. The CMS should have a dedicated file (something.json like composer.json or package.json) instead of using README.md, which is a very opinionated file and should remain free for the developer to format as they prefers.

[viktor]

Can you elaborate why it was a mistake? We’re discussing md/txt issue in Slack right now. So it’s a good time to chime in.

[kevinhaig]

Who is the end user here? If it is strictly developers then an .md only file makes sense. If it is read by folks with minimal development experience then a .txt only file makes sense.

What is contained in the read only typically incudes installation and sometimes special instructions, among all the other obligatory information, licensing, assets credits, etc.

To me there is a very good case to have both, but if you want only one, keep the readme.txt file as it will still load in git, and be in a better format for non techies.

[viktor]

This petition will be marked completed and closed. This is what the requirements will be for plugins, themes, and code snippets:

You will also need to ensure that your software provides the following three items of information:

1. Requires PHP header
2. Requires CP header
3. Either a README.md file in the software’s zip file — this is the preferred method — or a Description header. If neither of these are found, we will look for a README.md file in the software’s repository.

Plugins and Code Snippets

For a plugin or code snippet, the headers should be listed (one line for each header) at the top of the main .php file, like this:

/**
* Requires PHP: 7.2
* Requires CP: 1.4
* Description: (Note: this header is unnecessary if you are using a README.md file)
*/

You may include other headers if you wish, but they will be ignored by the ClassicPress Directory. (For plugins only, we can also read the headers and description if supplied in the plugin’s readme.txt file, but this will work only if it includes the Requires CP header. It may also lead to a less pleasing formatting of the description of your plugin in the ClassicPress Directory. So relying on this method is not recommended.)

Themes

For a theme, the headers should be listed (again, one line for each header) at the top of the style.css file, like this:

/*
Theme Name: Name of your theme
...
Description: A description of your theme.
Requires PHP: 7.2
Requires CP: 1.4
...*/

As indicated by the ellipses, you should typically include other headers too, though their presence serves other purposes and will be ignored by the ClassicPress Directory.

If the required headers are not present in the style.css file, the Directory will attempt to obtain them from the theme’s readme.txt file but, as with plugins, this will work only if that file includes the Requires CP header. Even then, this fallback may lead to a less pleasing formatting of the description of your theme in the ClassicPress Directory. Relying on this fallback is, therefore, not recommended.