Page MenuHomePhabricator

Improve OOUI's README.md/GitHub representation
Open, MediumPublic

Description

Let's revisit our README.md. File of v0.24.0

Ideas:

Intro

  • Be more verbose about library's strengths and key features: Accessibility, em based sizing, number of widgets, modularity, LESS variables comes to mind
  • We're mixing terminology, once toolkit, once library. Let's make use of one consistently. Preferably “library”.

“Quick start”

  • Clarify and reduce Quick start, remove f.e. “if you don't want to use npm”, grunt-cli is included in grunt, …

“Loading the library”

  • Extend loading by using the library?
  • Start with what dev would normally need to use and explain further application below.
  • “The remaining files make it possible to load only parts of the whole library.” isn't explanatory

“Versioning”

“Contributing”

  • <rant>These two sentences explain on its own, why our software (in general) is not an inviting place to start with becoming a contributor:</rant>

“You will need a Wikitech account which you can use to login to Gerrit, our code review system.
You will need a Wikimedia account, which you can use to login to Phabricator.”

  • Add LESS to linted files
  • SVGO sounds nice, but isn't integrated into our CI, also why do we have --disable=cleanupIDs as option?
  • “You should expect to get code review within a day or two.” sounds nice, maybe a bit optimistic?
  • “A new version of the library is cut and released most weeks on Tuesdays.” KISS => “A new version of the library is released most weeks on Tuesdays”

“Release”
It might be helpful, but do we need this here?

Additional ideas:

  • Moving “Versioning” further down, underneath “Contributing”
  • GitHub: Adding CSS gzip size JS gzip size indicators as seen at https://github.com/twbs/bootstrap
  • Adding a “Community” section as seen at https://github.com/twbs/bootstrap
  • Adding a copyright and license section
  • Adding an explicit Contributing.md file
  • Explaining the support of both, PHP and JS side-by-side further
  • Like the browser support matrix at Bootstrap, with our architecture it might be hard to integrate. But any link to supported browsers would help contributors as it's about a user interface library!

GitHub Tagline
Currently reads “Modern JavaScript UI toolkit. This is a mirror from https://gerrit.wikimedia.org. See https://www.mediawiki.org/wiki/Developer_access for contributing. Visit the main website for further documentation: https://www.mediawiki.org/wiki/OOjs_UI” turn into

  • “Modern JavaScript UI toolkit. Main website: https://www.mediawiki.org/wiki/OOjs_UI. This is a mirror from https://gerrit.wikimedia.org.” Remove contributing link into “Contributing” section.

GitHub Topics

  • Already added “ui, ui-components, oojs-ui, icons” to the rather new GitHub topics

Inspirations taken from README Maturity Model – thanks @Jdforrester-WMF, Bootstrap and SemanticUI

Your thoughts are welcome…!

Event Timeline

Volker_E created this task.Oct 26 2017, 7:59 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 26 2017, 7:59 PM

Change 386709 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[oojs/ui@master] README: Simplify and move “Versioning” section

https://gerrit.wikimedia.org/r/386709

Volker_E updated the task description. (Show Details)Oct 26 2017, 8:42 PM

Change 386714 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[oojs/ui@master] README: Simplify “Contributing” section slightly and add LESS lint hint

https://gerrit.wikimedia.org/r/386714

Volker_E updated the task description. (Show Details)Oct 26 2017, 9:38 PM
Volker_E moved this task from Backlog to Doing on the OOUI board.Oct 28 2017, 2:57 AM

Related: T104669: Improve OOjs UI's readme in doxygen generated documentation.

Also the svgo stuff is documented at https://www.mediawiki.org/wiki/Manual:Assets - the linked git commits probably have some explanations.

Change 386709 merged by jenkins-bot:
[oojs/ui@master] README: Simplify and move “Versioning” section

https://gerrit.wikimedia.org/r/386709

Change 386714 merged by jenkins-bot:
[oojs/ui@master] README: Simplify “Contributing” section slightly and add LESS lint hint

https://gerrit.wikimedia.org/r/386714

Volker_E updated the task description. (Show Details)Oct 28 2017, 10:58 PM

Change 387530 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[oojs/ui@master] README: Simplify “Quick start” section

https://gerrit.wikimedia.org/r/387530

Volker_E updated the task description. (Show Details)Oct 31 2017, 8:15 AM
Prtksxna updated the task description. (Show Details)Oct 31 2017, 10:31 AM

Change 387744 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[oojs/ui@master] README: Consistently refert to OOUI as library

https://gerrit.wikimedia.org/r/387744

Change 387744 merged by jenkins-bot:
[oojs/ui@master] README: Consistently refer to OOUI as library

https://gerrit.wikimedia.org/r/387744

Volker_E updated the task description. (Show Details)Oct 31 2017, 11:09 PM
bd808 added a subscriber: bd808.Nov 1 2017, 2:52 AM

From README.md:

  • You will need a Wikitech account which you can use to login to Gerrit, our code review system.
  • You will need a Wikimedia account, which you can use to login to Phabricator.

This can be simplified. The developer account (I'd really like us to call the LDAP account created via wikitech or https://toolsadmin.wikimedia.org a "developer account") can be used to authenticate to Phabricator. There is no absolute need for a separate Wikimedia wiki account for this.

From README.md:

  • You will need a Wikitech account which you can use to login to Gerrit, our code review system.
  • You will need a Wikimedia account, which you can use to login to Phabricator.

This can be simplified. The developer account (I'd really like us to call the LDAP account created via wikitech or https://toolsadmin.wikimedia.org a "developer account") can be used to authenticate to Phabricator. There is no absolute need for a separate Wikimedia wiki account for this.

@bd808 I've made some changes in https://gerrit.wikimedia.org/r/#/c/387530/ based on your advice. Could you please review and check if its an oversimplification?

bd808 added a comment.Nov 2 2017, 3:43 AM

@bd808 I've made some changes in https://gerrit.wikimedia.org/r/#/c/387530/ based on your advice. Could you please review and check if its an oversimplification?

The wording on PS5 looks good to me. I've started a discussion at T179461: Use the term "developer account" for Wikimedia LDAP accounts about making the term "developer account" more 'official'. We may end up with a better landing page for account creation instructions too, but that can be adjusted here (and a million other places) once we have a firm plan. Thanks for taking action on my suggestion so quickly. 😄

@bd808 Thanks for chiming in here too. Really appreciate your inputs and haven't had hope for a better “solution” on registering for developers addressing my rant so quickly. 😄

Change 387530 merged by jenkins-bot:
[oojs/ui@master] README: Simplify “Quick start” and "Contributing" section

https://gerrit.wikimedia.org/r/387530

Volker_E updated the task description. (Show Details)Nov 7 2017, 8:32 PM
From the description

“Release”
It might be helpful, but do we need this here?

We could move it to CONTRIBUTING.md should we choose to have one.

Adding a copyright and license section

Makes sense. I was also wondering if having the LICENSE-MIT file, as we already do, is enough.

Adding an explicit Contributing.md file

While this is a good practice, I was under the impression that it is a Github specific file. I don't see any harm in having the contents it would have in README itself.

Prtksxna added a comment.EditedNov 8 2017, 2:23 AM
From the description

Adding a “Community” section as seen at https://github.com/twbs/bootstrap

Sounds like a good idea! We'd want to include:

Any other ideas?

From the description:

Be more verbose about library's strengths and key features: Accessibility, em based sizing, number of widgets, modularity, LESS variables comes to mind

RTL support, theme-able, icon pack

Do we want to add this right at the top like in the case of Semantic UI?

Volker_E added a comment.EditedNov 8 2017, 2:40 AM

@Prtksxna To your first response, we're dealing with a certain reality and that is, that a good amount of volunteer developers might stumble upon the project via GitHub. My thinking is that we don't hurt anybody by adding CONTRIBUTING.md, but instead have an easy win at a certain audience.

@Prtksxna To “Community”: I'd also add wikitech-l mailing list link.

Change 390181 had a related patch set uploaded (by Prtksxna; owner: Prtksxna):
[oojs/ui@master] README: Add "Community" section

https://gerrit.wikimedia.org/r/390181

Volker_E updated the task description. (Show Details)Nov 9 2017, 4:04 PM

Change 390181 merged by jenkins-bot:
[oojs/ui@master] README: Add "Community" section

https://gerrit.wikimedia.org/r/390181

Volker_E triaged this task as Medium priority.Nov 9 2017, 4:15 PM
Volker_E removed a project: Patch-For-Review.
Volker_E updated the task description. (Show Details)
Prtksxna added a comment.EditedNov 10 2017, 2:10 AM

@Prtksxna To your first response, we're dealing with a certain reality and that is, that a good amount of volunteer developers might stumble upon the project via GitHub. My thinking is that we don't hurt anybody by adding CONTRIBUTING.md, but instead have an easy win at a certain audience.

Whether people stumble upon the project on Github, Gerrit, or NPM, they will be able to see the same contents on the README. The point of having a different CONTRIBUTING file on Github is that its highlighted when raising issues or sending PRs. We don't support those actions on Github.

I think we should have a wider consensus if we want to do this. Currently don't see the gain in splitting information into two files.

Change 390361 had a related patch set uploaded (by Prtksxna; owner: Prtksxna):
[oojs/ui@master] README: Re-arrange intro section

https://gerrit.wikimedia.org/r/390361

I didn't realize until now that this task was about Github representation :P

:)
Happy for a wider discussion. Pointing from a README.md to a CONTRIBUTING.md wouldn't hurt me as much. As we also think it's fine to have such file as we also have an AUTHORS.txt and a LICENSE-MIT file. All of those are conventions from different angles and if we are pointing IMHO we won't loose non-GitHub users while we might gain effectiveness for a group on the most popular platform.

Change 390361 merged by jenkins-bot:
[oojs/ui@master] README: Re-arrange intro section

https://gerrit.wikimedia.org/r/390361

Prtksxna updated the task description. (Show Details)Nov 28 2017, 4:24 AM
From the description:

GitHub: Adding CSS gzip size JS gzip size indicators as seen at https://github.com/twbs/bootstrap

Are you referring to https://github.com/ngryman/badge-size? Is the proposal to add an actual shield or just share that information? Which file(s) in particular do you want to highlight the size of?

Volker_E removed a subscriber: gerritbot.

@Prtksxna Yes, that was what I was referring to. My idea was a humbling about our options – maybe the core styles and packs could be useful? It depends on the numbers output.

Krinkle removed a subscriber: Krinkle.Jan 9 2018, 5:26 PM
Volker_E added a comment.EditedApr 17 2018, 4:55 AM

We could consider adding a bundlesize test, like in https://gerrit.wikimedia.org/r/#/c/406837/2/package.json, respectively https://github.com/siddharthkp/bundlesize