Change all README.txt files to README.md

Created on 1 April 2019, over 5 years ago
Updated 24 June 2024, 19 days ago

Problem/Motivation

In #3192842: Make our README more welcoming by converting it into an "entrypoint" into the Drupal ecosystem ā†’ we converted the base README file from README.txt to README.md. We should consider converting all other READMEs in the codebase as well.

---- original report ------

If we have a look at the following link
https://git.drupalcode.org/project/drupal
We will notice the nice gitlab interface :)

But we could make the project code even more readable with the .md files
something like https://git.drupalcode.org/project/anchor_link for example

README.md will be nice, but not sure if we should do the change for all .txt files, but not the robots.txt or alike functional files

Proposed resolution

Convert all README.txt files in core to README.md.
Change all references to these files from README.txt to README.md.

Remaining tasks

User interface changes

API changes

Data model changes

Release notes snippet

šŸ“Œ Task
Status

Needs work

Version

11.0 šŸ”„

Component
DocumentationĀ  ā†’

Last updated about 17 hours ago

No maintainer
Created by

šŸ‡ÆšŸ‡“Jordan Rajab Natshah Jordan

Live updates comments and jobs are added and updated live.
  • Novice

    It would make a good project for someone who is new to the Drupal contribution process. It's preferred over Newbie.

Sign in to follow issues

Merge Requests

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • šŸ‡øšŸ‡°Slovakia poker10

    This was done in #3192842: Make our README more welcoming by converting it into an "entrypoint" into the Drupal ecosystem ā†’ , but only for the main README.txt. I am reopening this as a follow-up to discuss/convert all other READMEs. See: #3389611-17: Update robots.txt with all README files core ships with ā†’

    The last patch needs to be updated - I think it will be the best to focus only on README files here (as the IS suggested initially). Thanks!

  • last update 9 months ago
    Patch Failed to Apply
  • šŸ‡®šŸ‡³India ravi kant Jaipur

    I am agree with @poker10
    The ticker is only for README.txt to README.md conversion but i saw that may files are updating which are not readme files. So only README files should update otherwise we will face broken deployment merge.

  • Hey,

    Here is the patch! Let me know any adjustment needed! Thanks

  • Status changed to Needs review 4 months ago
  • Status changed to Needs work 4 months ago
  • The Needs Review Queue Bot ā†’ tested this issue.

    While you are making the above changes, we recommend that you convert this patch to a merge request ā†’ . Merge requests are preferred over patches. Be sure to hide the old patch files as well. (Converting an issue to a merge request without other contributions to the issue will not receive credit.)

  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    I am at DrupalCon working on getting this patch in 22 to be applyable.

  • šŸ‡ŗšŸ‡øUnited States koppie

    I'm jumping on this issue as part of the mentored contribution at Drupalcon 24!

  • šŸ‡ŗšŸ‡øUnited States Chibullz023

    I am working on this issue as part of Mentored Contribution at Drupalcon 24!

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    I'm mentoring our table on this issue. So far there's @skessler, @koppie and @Chibullz023 working on this. We will create a MR but for now are focused on reviewing and updating the patch.

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    Note that we've been trying to update the patch from #22 to work with the latest 11.x code. One person in the group will start from scratch and not use the old patch. Once we have something to upload, we will. Then we will create the MR.

  • šŸ‡ŗšŸ‡øUnited States skessler Denver
  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    Rolled a new patch. Removed changes to composer.lock and other composer files.

  • last update 2 months ago
    Patch Failed to Apply
  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    Rerolled patch without /web

  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    Third time is the charm.

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    That patch applied cleanly to 11.x when I did:

    git apply --index -v Fixes-for-Drupal-3044974_2.patch
    

    but not with patch -p1.

    Afterwards, I do get some remaining README.txt files:

    ./core/lib/Drupal/Component/Discovery/README.txt
    ./core/lib/Drupal/Component/Plugin/README.txt
    ./core/lib/Drupal/Component/Assertion/README.txt
    ./core/lib/Drupal/Component/DependencyInjection/README.txt
    ./core/profiles/demo_umami/themes/umami/images/classy/README.txt
    ./core/profiles/demo_umami/themes/umami/js/classy/README.txt
    ./core/modules/system/tests/src/Functional/UpdateSystem/README.txt
    ./composer/Metapackage/README.txt
    ./composer/Plugin/VendorHardening/README.txt
    ./composer/Template/README.txt
    ./sites/README.txt
    ./profiles/README.txt
    ./modules/README.txt
    ./themes/README.txt
    

    and see it in some files:

    ./composer.lock:                        "[web-root]/sites/README.txt": "assets/scaffold/files/sites.README.txt",
    ./composer.lock:                        "[web-root]/modules/README.txt": "assets/scaffold/files/modules.README.txt",
    ./composer.lock:                        "[web-root]/profiles/README.txt": "assets/scaffold/files/profiles.README.txt",
    ./composer.lock:                        "[web-root]/themes/README.txt": "assets/scaffold/files/themes.README.txt"
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Metapackage/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Plugin/VendorHardening/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Template/README.txt
    ./composer/Generator/BuilderInterface.php: * See the README.txt file in composer/Metapackage for a description of what
    ./robots.txt:Disallow: /composer/Metapackage/README.txt
    ./robots.txt:Disallow: /composer/Plugin/VendorHardening/README.txt
    ./robots.txt:Disallow: /composer/Template/README.txt
    
  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    This patch covers the changes above and adds the composer folder. The composer folder is only found when cloning the git directory rather than downloading with composer.

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    Applies cleanly with git apply --index -v 3044974_patch_from_git.patch.

    Did still notice the following but there are no README.txt files left.

    ./composer.lock:                        "[web-root]/sites/README.txt": "assets/scaffold/files/sites.README.txt",
    ./composer.lock:                        "[web-root]/modules/README.txt": "assets/scaffold/files/modules.README.txt",
    ./composer.lock:                        "[web-root]/profiles/README.txt": "assets/scaffold/files/profiles.README.txt",
    ./composer.lock:                        "[web-root]/themes/README.txt": "assets/scaffold/files/themes.README.txt"
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Metapackage/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Plugin/VendorHardening/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Template/README.txt
    
  • šŸ‡ŗšŸ‡øUnited States koppie

    The patch applies cleanly! However, I noticed one remaining issue: modules/README.txt gets deleted. Was that intentional?

    I'm keeping this marked as "needs work" until this last issue gets resolved.

  • Status changed to Needs review 2 months ago
  • šŸ‡ŗšŸ‡øUnited States koppie

    I'm uploading my own version of the patch with only one change: rename modules/README.txt to modules/README.md, instead of deleting it. Please test.

  • Status changed to Needs work 2 months ago
  • šŸ‡ŗšŸ‡øUnited States smustgrave

    Can we change to an MR please.

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    @smustgrave We will be once we have the patch working as noted above.

  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    This new patch should cover all the issues.
    Thank you for the reviews and feedback.

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    Thanks @koppie and @skessler :) I'll review and if it's good or close, I'll get it moved to an MR. I know you both are heading out now.

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    @skessler I'm still seeing below but other issues do seem to be fixed.

    @smustgrave Please note that @skessler is hoping to move this to an MR as a learning opportunity over the next couple days.

    Kristens-MacBook-Pro:drupal11 kristenpol$ grep -r README.txt .|more
    ./composer.lock:                        "[web-root]/sites/README.txt": "assets/scaffold/files/sites.README.txt",
    ./composer.lock:                        "[web-root]/modules/README.txt": "assets/scaffold/files/modules.README.txt",
    ./composer.lock:                        "[web-root]/profiles/README.txt": "assets/scaffold/files/profiles.README.txt",
    ./composer.lock:                        "[web-root]/themes/README.txt": "assets/scaffold/files/themes.README.txt"
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Metapackage/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Plugin/VendorHardening/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Template/README.txt
    
  • Status changed to Needs review 2 months ago
  • šŸ‡ŗšŸ‡øUnited States koppie

    Whoops, @skessler's latest version still deletes modules/README.txt. Here's a new version that renames instead of deletes. @kristen-pol I'll let you create the MR since I've never done that in the context of d.org. :-)

  • Status changed to Needs work 2 months ago
  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    It's getting there :)

    @koppie If you are able, I'm seeing these still in #44.

    Kristens-MacBook-Pro:drupal11 kristenpol$ grep -r README.txt .|more
    ./composer.lock:                        "[web-root]/sites/README.txt": "assets/scaffold/files/sites.README.txt",
    ./composer.lock:                        "[web-root]/modules/README.txt": "assets/scaffold/files/modules.README.txt",
    ./composer.lock:                        "[web-root]/profiles/README.txt": "assets/scaffold/files/profiles.README.txt",
    ./composer.lock:                        "[web-root]/themes/README.txt": "assets/scaffold/files/themes.README.txt"
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Metapackage/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Plugin/VendorHardening/README.txt
    ./core/assets/scaffold/files/robots.txt:Disallow: /composer/Template/README.txt
    ./composer/Generator/BuilderInterface.php: * See the README.txt file in composer/Metapackage for a description of what
    ./robots.txt:Disallow: /composer/Metapackage/README.txt
    ./robots.txt:Disallow: /composer/Plugin/VendorHardening/README.txt
    ./robots.txt:Disallow: /composer/Template/README.txt
    
    
  • Status changed to Needs review 2 months ago
  • šŸ‡ŗšŸ‡øUnited States koppie

    Thanks @kristen-pol, I've gone through one more time to find any remaining references to README.txt in the code base, and I think I've got them all. Please test.

  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    Thanks @koppie and @kristen-pol, for your help. I think I uploaded the wrong file last time because I know I made those changes.

    Thanks,
    Steve

  • šŸ‡¬šŸ‡§United Kingdom rachel_norfolk UK

    Just re-tagging with the official tag :-)

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    @rachel_norfolk Thanks! Looks like you (or someone) fixed all the others too :)

    @skessler if you have time soon, please review the patch from @koppie and, if it looks good, create an MR. Then we can get this issue moved forward.

  • Status changed to Needs work about 2 months ago
  • šŸ‡ŗšŸ‡øUnited States smustgrave

    Since it's been a few days going to move to NW for the MR.

    Leaving all tags as this should still be reserved for those who worked on it in Portland

    This may help too https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-dr... ā†’

  • šŸ‡ŗšŸ‡øUnited States Kristen Pol Santa Cruz, CA, USA

    @skessler asked for help to change this into an MR via slack a few days ago but Iā€™m traveling and unable to help.

    @smustgrave you have any availability to help on mentoring?

  • Merge request !8115All Readme updates to .md files ā†’ (Open) created by skessler
  • Pipeline finished with Canceled
    about 2 months ago
    Total: 704s
    #175461
  • Status changed to Needs review about 2 months ago
  • Pipeline finished with Failed
    about 2 months ago
    Total: 871s
    #175472
  • It seems that simply changing the extension doesn't preserve the good formatting for md files. I think they need to be updated to the correct formatting for code, tables, links, etc. This will further improve the visual perception and usability

  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    Maks,

    The plan had been to make these changes and then open a new ticket to make all of the changes in the files to include Markdown. I am fine either way. It is going to take me a bit to get all the Markdown changes made.

    Thoughts?

    Thanks,
    Steve

  • Status changed to Needs work about 2 months ago
  • šŸ‡ŗšŸ‡øUnited States smustgrave

    Leaving novice tag for those who worked on in Portland. Can the MR be rebased? appears to have test failures

  • Status changed to Needs review about 1 month ago
  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    @smustgrave, sorry for the basic question but I am trying to do the rebase I cannot find the correct name for the remote branch. I would think it should be origin/issue-3044974 but my local git client is reporting that the branch does not exist.

    Thank you for the help.

    Thanks,
    Steve

  • šŸ‡³šŸ‡æNew Zealand quietone New Zealand

    @skessler, Just after the Issue Summary there is a 'show commands' link which while display information about the fork and branch. And, there is a how to for rebasing a merge request ā†’ as well. Linking that in case you need it. I hope that helps.

  • Status changed to Needs work about 1 month ago
  • šŸ‡ŗšŸ‡øUnited States smustgrave

    Thanks @quietone

    I'm also available on slack in #contribute or #first-contribution to further help.

  • Pipeline finished with Failed
    about 1 month ago
    Total: 129s
    #191102
  • šŸ‡ŗšŸ‡øUnited States skessler Denver

    I am not sure what happened here but I was sure I had posted an update.
    The issue with the merge request is that we are trying to change the composer.lock. At some point the composer.lock file needs to change but I think this should happen the next time Composer is run for Drupal Core. I am not sure what this process is. But the hashes in composer.lock are changing so this means that Composer is updating composer.lock at some point.

    Thoughts about leaving out composer.lock from the MR?

    Thanks,
    Steve

Production build 0.69.0 2024