Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

lts-doc: sort documentation alphabetically #3652

Closed
wants to merge 6 commits into from

Conversation

tflanagan
Copy link
Contributor

As a follow up to #3651, and to #393, I've started from the top and am working my way down.

This is a WIP! Against v4.x!

I am posting this now because it is a big diff and will need eyes.

Docs that have been completed:

  • assert
  • buffer
  • child_process
  • cluster
  • console
  • crypto
  • dns
  • filling in as I go

Help is more than welcome!

@Fishrock123 Fishrock123 added the doc Issues and PRs related to the documentations. label Nov 4, 2015
@Fishrock123
Copy link
Contributor

Awesome!

@tflanagan
Copy link
Contributor Author

Fixed.

Reorders, without contextual change, the assert documentation
alphabetically.
@Trott
Copy link
Member

Trott commented Nov 4, 2015

/cc @nodejs/documentation

Reorders, with minimal content duplication, the buffer documentation
alphabetically.
Reorders, with no contextual changes, the child_process documentation
alphabetically.
@tflanagan tflanagan changed the title doc: sort documentation alphabetically lts-doc: sort documentation alphabetically Nov 4, 2015
Reorder, with no contextual changes, the cluster documentation
alphabetically.
Reorders, with no contextual changes, the console documentation
alphabetically.
@jasnell
Copy link
Member

jasnell commented Nov 4, 2015

Note that this cannot land directly against v4.x, it would need to land against v4.x-staging.

Also, my concern with this is that if the equivalent changes are not made in master, it will become much more difficult to simply cherry pick commits for doc changes from master to v4.x-staging in the future. Ideally, these changes would land in master first, then get cherry-picked and modified back in a PR to v4.x-staging.

/cc @nodejs/lts

@tflanagan
Copy link
Contributor Author

With that comment, @jasnell, I'm holding off on more changes I'm doing the easy ones.

Are you saying I should checkout a new branch off of master and make the changes there? I figured that with master being at v5/v6, the changes in the docs would be too much for backporting.

@jasnell
Copy link
Member

jasnell commented Nov 4, 2015

I don't want to discourage the work, it's good stuff. However, the process we've been following the landing in Stable and LTS branches is to first land things in master then cherrypick back to the relevant branches. For LTS, the commits land first into v4.x-staging and are pulled into the v4.x only when a release is actually cut. This gives us the most flexibility when we need to do quick releases to address things like security updates, etc. By landing things in master first, it's easier for us to backport future commits.

For instance, if we go through a reorder everything in v4.x but don't make the corresponding change in master, then someone goes and makes edits in the same doc in master, when it's time to pull those back we end up having to reconcile a number of conflicts as opposed to a simple git am with a few tweaks here and there.

Right now, the deltas between v5/v6 are small enough that pulling stuff back to v4 is simple. It will get more difficult as the gap widens but even then, we want to minimize the differences between v4 and master as much as possible. As we go along, there will be changes that need to be made that only apply to v4. Those would still need to land as commits to v4.x-staging.

I don't want to discourage this work, however. It should just be done in a way that ensures parallel changes are being made in master and v5.

Reorders, with no contextual changes, the dns documentation
alphabetically.
@tflanagan
Copy link
Contributor Author

Okay, @jasnell, so the action to be taken is to open a PR against master?

If so, I'll start the diff/merge on my end, close this (actually I can't), and open a new PR against master.

@jasnell
Copy link
Member

jasnell commented Nov 4, 2015

Yes. And I would recommend one commit per file modified the way you've been
doing it. Thank you. I know it's a pain.
On Nov 3, 2015 6:17 PM, "Tristian Flanagan" notifications@github.com
wrote:

Okay, so the action to be taken is to open a PR against master?


Reply to this email directly or view it on GitHub
#3652 (comment).

@tflanagan
Copy link
Contributor Author

closing.

re: #3662

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants