Documentation pages

We currently have a mixture of lower case and differently capitalized case for software names throughout the documentation pages. It would be good to have consistent capitalisation and the following are what I think should be used, according to the sites linked:

Mixed capitalization

ESLint - https://eslint.org
CSpell - https://cspell.org
PHPStan - https://phpstan.org
PHPUnit - https://phpunit.de
MkDocs - https://squidfunk.github.io/mkdocs-material

Ordinary single letter capital

Composer - https://getcomposer.org/
Stylelint - https://stylelint.io
Nightwatch https://nightwatchjs.org/

All capitals or all lower case (but not mixed)

PHPCS or phpcs - https://github.com/PHPCSStandards/PHP_CodeSniffer

The actual job names in .main.yml cannot be changed. These are all in lower case except for the 'PHP' in the 'max PHP version' variants.

Fully agree with #3.

Thanks. I will search out the incorrect ones and fix them.

Added note to the summary about the original https://www.drupal.org/docs/develop/git/using-gitlab-to-contribute-to-dr... →

Following up #3 and #4, I have just pushed changes to fix the mixed capitalization for ESLint, CSpell, PHPStan and PHPUnit. (MkDocs was already correct). I will do the changes for the others next.

Thanks for all these fixes. I'll check the full MR once ready, but so far it's looking great!

I have added the hint for ckeditor - from end of this thread https://drupal.slack.com/archives/CGKLP028K/p1716902409940869

There's quite a lot here, so this is ready for review. I won't add any more new changes now, so you can review this ready for merging.

I made a really minor fix. Running pipelines https://git.drupalcode.org/project/gitlab_templates/-/pipelines/326141
If all green I'll go ahead and merge. Thanks for making sure the languages stays consistent all throughout the documentation!

Merged. Thanks!

Thank you for noticing that and fixing it.

There are more docs changes, as I have not reviewed all the pages yest, some are still the originals. Before two weeks elapses I may open a new MR here for the next changes, before the issue closes.

The first commit in MR281- docs part 6 is a re-write of the ESLint page by @ptmkenny from this slack thread

Adding this from comment #12 on 💬 Disabling OPT_IN_TEST_CURRENT not working Active from @liam-morland

--

It would be very helpful if the Templates behavior in contrib modules page included a table to help people select what template version to use, something like this:

Also, the .gitlab-ci.yml template includes the text "For information on alternative values for 'ref'". This isn't very helpful if you don't know what can be configured with ref. I suggest changing this text to something like "You can choose what version of Drupal core to test on by setting the value of 'ref' To learn about the options, see https://project.pages.drupalcode.org/gitlab_templates/info/templates-ver...".

--

Fully agree on the second part. As for the first part, I agree that we can add some extra info or even an informative table, but as we only have one branch, it would be misleading to have Drupal 10 linked to 1.5.x-latest, because that's never going to get any additional changes or bug, it is just a tag.

I'd put something like this instead:

The templates are designed to keep up with Drupal versions. "Current" represents the recommended version of Drupal at that moment in time, so if new versions are released, "current" will change, whether it is a new minor or a new major (less common). With "current", the concept of "next" or "previous", whether it is "minor" or "major", will also shift.

For example, tag 1.6.0 made the switch for "current" to be Drupal 11. Before that, "current" was Drupal 10.

I noticed that the description of the second commit list was wrong, it said "What commits are in main but not yet in a tagged release?" but it was actually showing "What commits are in main but not yet in default" so I fixed the description. We don't often have a difference, because most times the default-ref is updated when a new tagged release is made. But at the current moment we have 1.6.10 but 'default' is still at 1.6.9. That's fine. I added a third commit list link, which shows what the second link was meant to show, namely what is in 'main' but not in a tagged release.

I changed the format for the new link, and could do the same for the other two if this is more readable. Not sure yet. Here's what the updated page looks like

I'm going to merge the current MR as it's a good round of improvements. As usual, we can open new ones. Great improvements!

Thanks for merging. I forgot to comment that one page had a incorrect internal link, which I fixed. The path needs to be relative to the current page not the document top-level. I guess we just have to check these things manually, as they are not found by any automatic checking.

Maybe we can do an internal task to check that. I found this which could be useful: https://github.com/tcort/markdown-link-check
This could be done in a follow-up as this issue is for documentation updates.

Good find. I have opened ✨ Use markdown-link-check to verify .md links Active

Automatically closed - issue fixed for 2 weeks with no activity.

jonathan1055 → changed the visibility of the branch 3473000-doc-update-5 to hidden.

jonathan1055 → changed the visibility of the branch 3473000-doc-update-6 to hidden.

MR319 is ready for review. Given that the allow_failure work is now in 'default-ref' I think it would be good to get this updated document page published.

There is always lots more to update in the docs, I have a long list, but will open new MR when I get on to that, so that 319 can be reviewed and won't be changing.

Agree. I've reviewed the changes and they look good, so I've merged MR319.
Marking as Fixed for now, but feel free to create a new MR and change the status of the issue.

Thanks for merging this. Just looked at the real published page and the formatting is not the same as when viewing the updated file in the issue fork (which is the only way I know how to check it when making changes). The numbered list has not been rendered, see attached screen shots.

I'm not sure what is wrong with the source file. Maybe we need to pursue ✨ Use markdown-link-check to verify .md links Active and that may identify incorrect formatting.

Setting to 'active' ready for next documentation MR.

Good catch, so far this https://project.pages.drupalcode.org/gitlab_templates/help/documentation... is the best way I've found to test everything locally as it will look like on the real site, but it's not straight forward and needs some local tools.

jonathan1055 → changed the visibility of the branch 3473000-doc-update-7 to hidden.

Coming here from https://drupal.slack.com/archives/CGKLP028K/p1739920511290749

I don't see this mentioned anywhere at https://project.pages.drupalcode.org/gitlab_templates/jobs/upgrade-status/ or otherwise. Google search is failing me. I've got a project I'm getting pinged about for a D11 issue. I'd love to run the upgrade status job via the bot. But if I do that, it's defaulting to the current core (11.1.x) and trying to check for D12 compatibility. I started a manual pipeline, and I didn't see any way to control "No, I want you to use D10 to run upgrade status to confirm D11 is cool".

1. How do you do this?
2. Shouldn't this be the default config for Upgrade status jobs? :sweat_smile:

The answer is when creating a manual pipeline, although there's no obvious choice in the initial list of variables to configure, if you manually set DRUPAL_CORE at last row of the form to ^10 or 10.4.2 or whatever you want, and then tweak the visible RUN_JOB_UPGRADE_STATUS variable to 1, you'll get what you need (a test run against previous major that then checks upgrade_status against the current major you're porting to)...

I found a bug in our scripts/unformatted-links.php which only checked the first url in each line. I had errors in the updated .md but the check code job did not detect them. I've fixed the script now, pushed the change, and the job fails as required.

The links are now fixed and the updated stylelint page can be viewed in the repo here. I have made a few more changes that were on my list, and this is now ready for review and feedback.

Thanks for fixing the link checker code.

Merged this new round of improvements. Thanks!

"Thanks for fixing the link checker code."

Well, it was my invention and so I felt I needed to fix it :-)

This MR dealt with a lot of the doc updates that I had been collecting, but I still have a bunch of things for the phpunit job page (which were too complex to quickly add in here this time). Setting back to 'active' to prevent closure in two weeks.

Also we have some internal standards and conventions for our jobs and documentation. It might be nice to have them recorded in a page somewhere. Maybe that's a new separate issue, and it could wait until we can test it with 📌 Allow testing documentation pages via MRs Active

Agree that we should probably wait until the per-MR environment issue is done.
Then we can probably expand this section: https://project.pages.drupalcode.org/gitlab_templates/help/contributing/ (same page or subsections).

I have updated the PHPStan page with a section on preventing object oriented hooks from causing errors on phpstan (previous major) due to unknown attributes.

Okay, I didn't notice the branch I was pushing to was already merged.

New branch and MR opened. Hopefully that's somewhat right now.

jonathan1055 → changed the visibility of the branch 3473000-doc-update-8 to hidden.

The issue fork needed updating, which I've done. You have all the commits from the previous branch in yours, but the overall changes are just your new ones, so I guess this is OK.