Add readme.txt and related update script
#72
Conversation
|
To anybody reviewing the content here, I specifically want to encourage you to update this PR directly to iterate on the content. People often shy away from updating someone else's PR, but the |
| * | ||
| * @return {Promise<[]WPModuleDescription>} Promise resolving to module description list. | ||
| */ | ||
| exports.getModuleDescriptions = async ( modulesDir ) => { |
There was a problem hiding this comment.
This is now in here since pretty much the same code was needed to extract the module header translations (npm run translations command) as it was needed to update the list of modules within the readme (the new npm run readme command).
| const readmeFile = path.join( '.', 'readme.txt' ); | ||
| const fileContent = fs.readFileSync( readmeFile, 'utf8' ); | ||
| const newContent = fileContent.replace( | ||
| /(the following performance modules:\s+)((\*.*\n)+)/, |
There was a problem hiding this comment.
Note that this must always match the exact wording preceding the module bulleted list in the readme.txt file. So if you update that bit in the readme.txt, make sure to update it here as well.
| * @property {string=} milestone Optional milestone title, to update the changelog in the readme. | ||
| * @property {string=} token Optional personal GitHub access token, only relevant for changelog updates. | ||
| */ | ||
|
|
There was a problem hiding this comment.
Maybe missing the object defined above?
There was a problem hiding this comment.
Hmm, can you clarify what you mean by this?
There was a problem hiding this comment.
Sure, I see a definition for an object WPReadmeCommandOptions and properties in this case milestone and token but I don't see the object itself in the doc, is this maybe document as part of the command ?
|
|
||
| **Features** | ||
|
|
||
| * Images: Add WebP for uploads module. ([32](https://github.com/WordPress/performance/pull/32)) |
There was a problem hiding this comment.
The description could be a bit more user friendly, "add WebP for uploads module" probably doesn't speak much to many folks
There was a problem hiding this comment.
I think these are generated from the PR themselves. Should we update the PR then @felixarntz?
There was a problem hiding this comment.
@JustinyAhin Correct, in that case we should change the PR title.
@ThierryA Do you have a suggestion on what it could be while still being concise? I'm personally okay with it, maybe we can clarify what the module does, but I also think we should keep it short.
|
@mitogh Updated based on your feedback! Also replied to your other comments (cc @ThierryA @JustinyAhin). |
Fixes #40
This PR is a starting point for the plugin's
readme.txtfile. It is a first content proposal for the readme itself, but in addition to that the PR includes a new related script callable vianpm run readmethat will help automatereadme.txtupdates in the future. Here's what that script does:npm run changeloglogic that was previously implemented in Add changelog generator script #51.Here's how to use the script:
npm run readme: This way it'll only update the module list. Try changing it to something else in thereadme.txtfile and then run this command, to see how it will always update the content to the names and descriptions of all modules within the codebase.npm run readme -- -m "1.0.0-beta.1": This way it'll also (in addition to the module list, see above) update the changelog section for the given milestone (right now we only have1.0.0-beta.1). If that changelog section doesn't exist yet, it'll add it right below== Changelog ==, otherwise it'll replace the existing section with the latest content. Try changing the content for that release to something else or add some dummy changelogs for other (non-existing) versions and then run the script to see how it always puts the latest changelog intoreadme.txt.This PR needs two types of reviews: On the one hand, it needs engineering review and testing for the new
npm run readmescript. On the other hand, it needs content review for the initial proposal for the readme itself. Let's keep in mind that this doesn't need to be perfect or the final state of the readme (we can always add more details later), but it should at least be good for a start and a minimum foundation with which we could potentially release a first version of the plugin.