[doc] Improved readme and all contributors

[adangel]

Describe the PR

I tried to improve our README. And also add all-contributors (https://allcontributors.org/) (but without the bot yet).

Resources used:

• https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
• https://www.makeareadme.com/
• https://allcontributors.org/

Preview: https://github.com/adangel/pmd/blob/improved-readme/README.md
Preview credits: https://github.com/adangel/pmd/blob/improved-readme/docs/pages/pmd/projectdocs/credits.md

Much more colorful 😄

Questions, suggestions:

• Should we add the pmd logo at the top?
• Should we really use all contributors?
  • It's easy to find the code contributors, but much harder to find other contributors (issue reporter, tester, ...)
  • add another language/framework to the mix: nodejs...
• The Demo looks very unspectacular - I guess, we should create a (gif) video
  • https://github.com/icholy/ttygif
  • https://asciinema.org/
  • https://terminalizer.com/ (with this fix: fix GL_INVALID_OPERATION on render faressoft/terminalizer#154)
  • https://github.com/phw/peek
  • https://github.com/HasinduLanka/screencorder
  • https://github.com/xlmnxp/blue-recorder
• Not sure, if we should keep the snapshot of pmd-eclipse-plugin here...

[pmd-test]

	1 Message
📖	No java rules are changed!

Generated by 🚫 Danger

[adangel]

I finally found a program, that kind of works to record screens/single windows under wayland: https://github.com/HasinduLanka/screencorder

Here's my try:

[oowekyala]

Thanks, this looks great :)

[adangel]

There's also the old file https://github.com/pmd/pmd/blob/master/docs/pages/pmd/projectdocs/credits.md

[adangel]

I've now added the first 100 github contributors with the following script (maybe it's useful for others):

export PRIVATE_TOKEN=....
curl https://api.github.com/repos/pmd/pmd/contributors?per_page=100 > pmd-contributors.json
for i in $(cat pmd-contributors.json | jq -r '.[].login'); do
  echo $i
  npx all-contributors add $i code
  sleep 1
done

This API only provides the first top 100 contributors (see also https://github.com/pmd/pmd/graphs/contributors)

[adangel]

Better screencast:

pmd-demo.mp4

[adangel]

It seems, that only gifs work in README.md files, although you can upload videos in comments (https://github.blog/2021-05-13-video-uploads-available-github/)

For creating the screencast, I used gnome and https://github.com/EasyScreenCast/EasyScreenCast
This will create a webm video.

With ffmpeg, it can be converted into mp4: ffmpeg -i pmd-demo.webm -r 15 -s 708x484 pmd-demo.mp4

Or into a high quality gif (http://blog.pkh.me/p/21-high-quality-gif-with-ffmpeg.html):

ffmpeg -i pmd-demo.webm -vf "fps=3,palettegen" -y pmd-demo-palette.png
ffmpeg -i pmd-demo.webm -i pmd-demo-palette.png -lavfi "fps=3 [x]; [x][1:v] paletteuse" -y pmd-demo.gif

[adangel]

Should we add the pmd logo at the top?

We should probably do this for pmd7, but not for pmd6

Should we really use all contributors?
It's easy to find the code contributors, but much harder to find other contributors (issue reporter, tester, ...)
add another language/framework to the mix: nodejs...

I guess, it makes sense to add the bot (https://allcontributors.org/docs/en/bot/overview) in order to easily add new contributors.

We have however older contributors (https://github.com/pmd/pmd/blob/master/docs/pages/pmd/projectdocs/credits.md) which we need to migrate....

If the list is too big in README.md, we might move it into CONTRIBUTORS.md

The Demo looks very unspectacular - I guess, we should create a (gif) video

The new demo is simple and basic... at least a moving picture

Not sure, if we should keep the snapshot of pmd-eclipse-plugin here...

Removed it.

TODOs:

• use git history to find more code contributors
  • I used only the issues. Using git commits is difficult, because we would need to map email addresses to users/identities.
• move contributors list out of README into a own file - maybe into the documentation, to replace credits.md?
  • I moved it into credits.md
• add/converts credits.md to contributors
  • I decided not to manually try to find each one on github. Instead I moved the "old" contributors into a own section "previous contributors". From now on, we should simply update .all-contributorsrc.

[adangel]

Just noticed: The readme in the pmd7 branch already has the new logo : https://github.com/pmd/pmd/blob/pmd/7.0.x/README.md

[adangel]

Here are the scriptlets I used to get the "issue"-contributors from github:

# download the issues... page 1 to 35, 100 per page
for page in $(seq 1 35); do
    curl \
      -H "Accept: application/vnd.github.v3+json" \
      "https://api.github.com/repos/pmd/pmd/issues?per_page=100&page=${page}&direction=asc&state=all" > pmd-issues-${page}.json
done

# extract the users
for page in $(seq 1 35); do
   jq -r '.[].user.login' pmd-issues-${page}.json >> pmd-issues-users.txt
done

# remove duplicates
sort pmd-issues-users.txt | uniq > pmd-issues-users-uniq.txt

# collect already added contributors
jq -r '.contributors[].login' .all-contributorsrc > contributors-users.txt
sort contributors-users.txt | uniq > contributors-users-uniq.txt

# contributors, that are already in .all-contributorsrc but additionally created bugs
comm -1 -2 contributors-users-uniq.txt pmd-issues-users-uniq.txt

# new contributors, who only created bugs
comm -1 -3 contributors-users-uniq.txt pmd-issues-users-uniq.txt

npm i
export PRIVATE_TOKEN=...

# Add new "bug" contributors:
for i in $(comm -1 -3 contributors-users-uniq.txt pmd-issues-users-uniq.txt); do
    echo $i;
    npx all-contributors add $i bug
    sleep 0.5
done

How many contributors?

$ jq -r '.contributors[].login' .all-contributorsrc|wc -l
702