Ditch readme.txt in favour of readme.md

Governance Petitions
#1

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:

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.

3 Likes
#2

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.

4 Likes
#3

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

2 Likes
#4

I am in favour of using the README.md :+1:

Some other discussions re this:

1 Like
#5

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.

2 Likes
#6

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.

2 Likes
#7

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.

3 Likes
#8

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.

3 Likes
#9

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…
2 Likes
#10

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.

6 Likes
#11

I think you convinced me to agree on keeping both :slight_smile:

3 Likes
#12

+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.

2 Likes
#13