Markdown'd readme, changelog, contributing and license files.

[TankOs]

Markdown-style files for better formatting and overall reading experience — especially on GitHub.

[LaurentGomila]

This was already discussed in the past, and as far as I remember, there were people (or maybe just me? 😁) against this modification.

[TankOs]

@LaurentGomila Yup, perhaps — but let's give this another try with some more pressure... ;-) Direct comparison: http://imgur.com/a/crlI4

[LaurentGomila]

Direct comparison: http://imgur.com/a/crlI4

... on github. What about the rest (ie. when you open it as a text file on your PC)?

[TankOs]

http://imgur.com/a/YZIsi

[mantognini]

http://imgur.com/a/YZIsi

Not that convincing if you ask me. Besides, we already have the website for a better reading experience.

[JonnyPtn]

In my humble opinion I'd prefer the markdown, but that may be because I rarely ever read readme text files (and when I do, it's usually just to find the github or website address), and also because I search github a lot when looking for tools/libraries and a nice readme can make all the difference

The files still seem perfectly readable to me in a text editor (even notepad!), but i appreciate making use of more markdown could eventually make it unreadable

[TankOs]

The changelog and contributor files are not even distributed with binary releases - where most of the links are included.

I'm with @JonnyPtn, it just makes a huge difference whether the readme makes the repository look like a passive Git mirror, or it's nicely integrated into the site.

Yes, viewing the changelog in the text editor isn't convincing, but still readable. If that's the only thing holding us back, then dropping the links is an option (the changelog also includes links to the online version for a yet better reading experience if all those links are too much).

[criptych]

If it's a question of readability, GFM should automatically make numbered issues into links (within a repository), so they could probably be left as they were.

For what it's worth, I'm in favor.

[LaurentGomila]

I know this sounds ridiculous, but what about Windows users who won't be able to double-click the .md files to open them in their default text editor?

Anyway: I won't block the PR this time, if we get enough agreement we can go ahead and merge it

[MarioLiebisch]

Well, considering how many projects just provide a README or INSTALL file rather than readme.txt or similar I don't think file extension alone is such a big issue. If you're into coding just a little bit, you should know how to open a random file in a repository. Plus there are now some popular editors that actually open the file association (like VS Code).

For zipped releases we could also think about using a conversion tool to create additional rtf or html documents for those lazy double click gits. :)

[TankOs]

@criptych That sounds great, thanks for the info.

@LaurentGomila How can they use a compiler if they fail to open a file with notepad.exe...? :P

@MarioLiebisch You forgot to also offer printed copies for those who are not into computers so much. ;-)

[TankOs]

Added logo and removed issue links, because issues are automagically linked by GitHub as mentioned by @criptych.

[TankOs]

Hey @eXpl0it3r, want to review this? 🌹

[mantognini]

IF people do think this is a good thing, it'd be better to git mv to keep a clean history/log for each individual file.

[eXpl0it3r]

I don't like the difference between the changelog here and on the website, as it requires additional work for every release.

[MarioLiebisch]

I don't like the difference between the changelog here and on the website, as it requires additional work for every release.

Sounds pretty trivial to me. We could just convert the change log using a script or render the markdown directly.

[TankOs]

I changed the markup because the output looked quite noisy to me. However I checked again at GitHub and it looks very similar to the website. I'll update it, so that we have less stuff to do.

[TankOs]

Adjusted + rebased.

[TankOs]

@SFML/sfml Can someone please approve this?

[LaurentGomila]

Why did you change the file names to upper case?

[mantognini]

Request: could you use git mv to rename files? This helps with the history.

[TankOs]

@LaurentGomila No specific reason. Just tell me how it's wanted and I'll do it.
@mantognini I can do that.

[LaurentGomila]

No specific reason. Just tell me how it's wanted and I'll do it.

If there's no reason to change it then it should stay the same.

[TankOs]

@LaurentGomila @mantognini Ping

[LaurentGomila]

I just noticed that CONTRIBUTING was upper case before your modification, it doesn't look consistent with the other files. Maybe this one should be changed to lower-case?

[mantognini]

I just noticed that CONTRIBUTING was upper case before your modification, it doesn't look consistent with the other files. Maybe this one should be changed to lower-case?

When I created this file it was a requirement to be in uppercase. Don't know if this still applies.

[jcowgill]

Request: could you use git mv to rename files? This helps with the history.

Git does not record file renames as part of commits, so this will have no effect. git mv is for most purposes equivalent to mv a b; git add -A a b.

[LaurentGomila]

When I created this file it was a requirement to be in uppercase

Why was it a requirement at that time? Is it a github thing?

[eXpl0it3r]

Why was it a requirement at that time? Is it a github thing?

Yes, it will display a notice at the top when creating a new issue. Hasn't been very effective though.

[TankOs]

I'd like to postpone renaming files to another PR. This one is about Markdown formatting. I updated the PR to have one clean commit again(!), instead of the (useless) renames as @jcowgill mentioned.

This is already 3 weeks old and has 29 comments about minor things.

[LaurentGomila]

Yes, let's merge it 👍

[TankOs]

Thanks; then feel free to approve the review, so that GitHub won't refuse the merge. ;-)

[mantognini]

Git does not record file renames as part of commits

I'm not sure about that -- or about what you meant. I can rename file and git will understand that. Example. Looking at the changes in this PR, the moves/renames was not registered. Note that GitHub log history for a file does not follow renaming, but some git clients do (e.g. source tree). It's a feature that's very handy -- probably not that much here with those files however. If you feel like changing the PR to accommodate for that, great. Otherwise, I'll survive. Let's just do it for source files.

[jcowgill]

@mantognini My point was the just doing git mv doesn't work because it is no different from renaming the files manually and running git add -A on them. Git does not store the rename information anywhere and only shows files as renamed because it detects that the new files and deleted files look similar. In this case the files were changed too much so Git's rename detection doesn't work.

[mantognini]

@jcowgill Thanks for the detailed reply. This really is a pity... One has to create a commit exclusively to rename things in order to keep the log history clean I guess. :-/

[JonnyPtn]

Hasn't been very effective though.

Perhaps because the file currently contains just a link to the website, instead of the actual content? MD will help make it an actual hyperlink, but I don't see a reason it couldn't just contain the details of the "contribute" page from the website