README.md: Unify formatting, modernize badges & update URLs (and move release_cycle to starlight)#21706
Conversation
crasbe
added
Type: enhancement
crasbe
left a comment
crasbe
left a comment
There was a problem hiding this comment.
I don't really understand what the improvement is with the inline links, except for unavoidable long lines 🤔
The idea is to follow one general standard for links. We currently use three different ways to store the links (inlined links, links at end of chapter, links at end of document), this way all links simply follow the inlined links syntax that is more common and recommended by the Github Syntax markdown guide. The other upside of that is that it becomes a bit easier to follow references when looking at it in raw text format. Even though I personally really dislike the reading flow of reference links (esp. in a README) we can also use per-chapter references if that is favored by the community, the current approach is however a complete mess of no coherent standard. |
Chapter-wise sounds like a good compromise. Perhaps it's worth documenting that somewhere, so that future documentation would be more coherent? |
Done :) |
crasbe
left a comment
crasbe
left a comment
There was a problem hiding this comment.
I know the content was not changed, but it still makes sense to make it better if possible.
Fixed 🫡 |
|
My most favourite words :D |
AnnsAnns
force-pushed
the
guide_readme
branch
from
56f1ae7 to
4649782
Compare
|
ah heck, the release_cycle got fixed into the commit, give me a sec to fix that |
AnnsAnns
force-pushed
the
guide_readme
branch
from
4649782 to
30fef83
Compare
|
Fixed and thank you for the review (as always 😉 ) |
4 participants
Contribution description
The current README kinda needed a spring cleaning, over the literal decade a lot of different ways to do formatting were added to the README resulting in absolutely no coherent formatting. This minor spring cleaning PR simply unifies the formatting. Since Github-flavored Markdown has become the quasi-standard and we are still on Github, I decided to follow the common Github Syntax as the guideline.
I also want to note (just to ease reviewers) that this PR does not change any text whatsoever. The text should pretty much be 1:1.
Aside from that I also removed/updated badges that were added 5 years ago and were fairly outdated. For example, the last stackoverflow question (of a total of 15 questions) was 1.5 years ago. Aside from that we don't even encourage stackoverflow for questions and it might lead users into asking questions on a site that doesn't get checked by active community members.
I also moved the learning resources section one layer higher. In the last README PR I already moved it above the community section but I've come to realize that even now the learning resources are beyond the cutoff line of the README, thus making it harder for beginners that are probably confused as is, to even find them.
The last thing this PR aims to do is to simply switch out soon-to-be dead links (such as the vision link) and while at it also move the release cycle to the guide site.
(There was also one completely dead link for the mailing list)
Testing procedure
Read the README and uhhh click the links? 😅
Issues/PRs references
Part of #21575