doc: renamed doc files to .md, adapted build scripts

[eljefedelrodeodeljefe]

This is for consistency and a little less noise for the eye
as in vm.markdown (2 against 8 chars)

Discussion on: #4726 and #4733

PR-URL:
Reviewed-By:
Reviewed-By:

[jasnell]

CI: https://ci.nodejs.org/job/node-test-pull-request/1298/

[cjihrig]

Is this what @rvagg was referring to in #4733 when he said:

Regarding renaming, I don't think you're going to get any support on this, it's unnecessary churn that makes the history too hard to follow. In general churn without strong justification gets a -1 around here for this reason.

[misterdjules]

Typo, this should still be Console.

[misterdjules]

The rest of the changes in this file should also be removed, as this PR is supposed to be about renaming files only.

[jasnell]

Yeah, it looks like this was done as a branch off the other PR branch so a lot of those other changes were carried over.

[eljefedelrodeodeljefe]

Yeah. Give me a second to chop the PRs. Git is funny about certain things.

[jasnell]

@eljefedelrodeodeljefe ... I appreciate the new PR to isolate this one change but this will need to be rebased off master and cleaned up to remove the additional changes from the other PR before it could land at all. Also, as @cjihrig and @rvagg indicate, I'm not sure if there's going to be enough consensus to get this landed. Personally I'm fine with renaming these, however.

[eljefedelrodeodeljefe]

@jasnell after the comments above I figured that... will likely close this in favor for a new one in a bit. Sorry for the noise.

About consensus: I know. It just seemed logic to me, while doing the other PR. I am okay with it not landing. cc @cjihrig

[jasnell]

No worries. Thank you for bearing with us @eljefedelrodeodeljefe ! The contributions are very welcome, it's just that sometimes it takes some tweaking here and there to get it just right! :-)

[rvagg]

thanks @eljefedelrodeodeljefe, having a place to discuss this separately is a good idea

[eljefedelrodeodeljefe]

@rvagg@jasnell that's alright for me. Just one thing: I'd like to have this closed or "paused" until #4733 is closed or merged. Because then I could just cherry-pick this commit. It's a lot easier for me of course :) I would have the same procedure for the typo fixes on #4733. When I would need to check out from master, and then cherry-pick from the PR there would be tons of merge conflicts.

Also currently investigating to rewrite history with this gist. The consequence though would be that the whole history would show the files as *.md.

[jasnell]

@eljefedelrodeodeljefe ... understood. I've applied the in progress label which should notify folks that it's a work in progress.

[eljefedelrodeodeljefe]

Thx @jasnell. Just a heads up. I am running:

git filter-branch --tree-filter 'if [ -f doc/api/_toc.markdown ] then mv doc/api/_toc.markdown doc/api/_toc.mdfi' --force HEAD 

This preserves the history, but changes filenames for all commits that refer to it. With node that's an operation that runs on 12k+ files. So for all the files it's probably gonna take another 20hrs on my machine. The history though looks good.

[jasnell]

that kind of forced push likely wouldn't work for master. We generally limit force pushes only to correct mistakes on landing only the most recent commits. It's hard to say what kind of impact that kind of bulk change would have.

[MylesBorins]

@eljefedelrodeodeljefe is there a reason for changing the file names in the git history and not just a single commit?

[eljefedelrodeodeljefe]

@jasnell Wouldn't the force push only apply to the PR branch and you would see problematic things in the diff? @thealphanerd this would be the consequence of the above command in order to preserve logs, since git mv would render the files git log with just one commit. You would need to git log --follow to see more though. I have seen several threads on the internets discussing this and that Linus is actively refusing to have a decent rename feature (for okay reasons).

[eljefedelrodeodeljefe]

@jasnell we have talked this PR through in the doc-WG meeting. @thealphanerd pointed out that as soon has you have cleared your backlog for LTS we could have a shot at merging this. Would you give me a ping as soon as this is done?

[MylesBorins]

Just tried landing this against staging and found the following conflicts

Unmerged paths:
(use "git reset HEAD <file>..." to unstage)
(use "git add <file>..." to mark resolution)
both modified: doc/api/tls.md
both modified: tools/doc/addon-verify.js
both modified: tools/doc/html.js

The conflicts themselves are pretty minimal. (edit) LGTM for lts (see below)

[eljefedelrodeodeljefe]

I am rebasing this right now.

[eljefedelrodeodeljefe]

@thealphanerd can you try again?

[eljefedelrodeodeljefe]

/cc @nodejs/documentation due to active PRs and lots of movements in the docs, quick response would be super appreciated.

[MylesBorins]

@eljefedelrodeodeljefe github is reporting there are still conflicts to resolve between this and master... have you taken a look at that?

Perhaps your master was not synced with upstream when you rebased?

[eljefedelrodeodeljefe]

rebase now green, make doc seems to render fine.

[MylesBorins]

The only conflict now is in the Makefile which is to be expected since there are multiple changes in the make file not present in v4.x

(Edit) LGTM see below

[techjeffharris]

LGTM. I personally prefer .md to .markdown, but if CTC decides that there isn't enough substance beyond renames to warrant the changes to the git history, I'm going to have to trust their judgement.

[MylesBorins]

I'm actually retroactively going to -0 on this... leaning towards -1

Even thought it was discussed above I didn't really think about the effect of completely wiping the history on the docs... although I'm not convinced that with LTS and stable being fairly in tune that is any less of an aesthetic choice than file name length. It feels like the data could turn out to be useful.

[eljefedelrodeodeljefe]

we'd still have the rev parsing, but what reassured me was @chrisdickinson that there was lots of precedences for removing and renaming before. See 2014. I don't mind too much, would be a nice fresh start though. If CTC decided against it, then we obviously just let it go.

[rvagg]

Is the Docs WG making a case for this? If so, perhaps we should hear a position from them?

The .markdown personally bothers me, I prefer .md, but it's pretty trivial and the desire for less churn easily overrides that—git blame gets very tedious trying to track down when/why something was changed when there's a lot of things moving around inside files and a change in filename adds an extra wrinkle to that process. I think we've set a fairly clear precedent in rejecting or pushing back on changes that introduce churn with little added value.

However, perhaps the Docs WG has a good case to make on why this is a good thing? I'm of the mind that handing more responsibility for docs/api to the Docs WG is a good thing in general and would prefer not to erect barriers to progress being made by people who are passionate about such things. I know others have a bit more of a mind for stricter quality-control but this is all about give and take.

[chrisdickinson]

This seems like a case where the potential gain is relatively minimal, but the potential loss is also relatively minimal — the gain being that we get to use the more idiomatic extension, .md, on both the new and old docs (and, maybe, that new docs don't need to use .markdown.) The loss is that it necessitates an extra argument to git log to track changes, and necessitates that folks use git blame $REV — a mild, but surmountable negative. Notably, no history is lost with this transformation.

It's a tough call, since it's a subtle upside vs. a subtle downside, but I lean towards merging this & backporting — I am not aware of anyone depending on the .markdown extension, as most folks seem to be using the generated .html or .json docs. I tend to think that this is enough of a nit that it will keep coming up, too, so by fixing this now we bolster the upside by saving ourselves time in the future.

[stevemao]

I agree with @chrisdickinson ,

The loss is that it necessitates an extra argument to git log to track changes, and necessitates that folks use git blame $REV

I believe it's just a bit hard for new git users. Most people who contribute to this repo are quite advanced. And what are the chances for new users to track the history of the .md files.

Although this is a nit PR, I believe the upside > downside.

[MylesBorins]

landed in 0800c0a

edit: worth mentioning that this was tested locally. I build the docs and made sure that the html looks exactly as it should

[eljefedelrodeodeljefe]

Awesome, thx everyone. Even though it's churn here it stands for renovation, yay!

[MylesBorins]

@eljefedelrodeodeljefe how long have you been sitting on that graphic?

[eljefedelrodeodeljefe]

I had to download and install Illustrator for an hour or two 😤

[stevemao]

Sorry for the late response @eljefedelrodeodeljefe , even git-mv didn't work?

[eljefedelrodeodeljefe]

@stevemao it is git mv. I think it's just git's or GitHubs diffing that shows it wrong.

[silverwind]

@eljefedelrodeodeljefe can you open a backport PR for this against v4.x? Would make landing doc stuff on LTS easier.

[MylesBorins]

@eljefedelrodeodeljefe ping re backport 😄

[eljefedelrodeodeljefe]

Sorry, yes, just haven't had a chance to look into the procedure. Will likely do it tomorrow. Sorry for the delay.

[eljefedelrodeodeljefe]

@thealphanerd#7507 cc @silverwind