Old version of Githbook had a clean way of seeing all the "commits" in a certain version and how it made it different (a change request) from other or main version it can be merged into.
Maybe am missing where I can find it in beta Gitbook?
Any word on when this can be expected? We currently have a draft that we are now ready to publish, but other changes have been made to the published version since we started it. As far as I can tell there is no way to merge only the changes we want without overwriting all the work we've done since..? Or am I missing something? I can't see any branches for each of our drafts in GitHub, just master and develop. Had the drafts been branches I could have at least done it directly in git.
@Nicolas Thanks for the detailed explanation. All makes sense.
From my perspective "versions" are not that useful. Especially if the target audience is software teams, doing agile, drafts (or branching of a version/revision) is more useful and natural.
I know in terms of v1/v2 api versions might seem handy, but most people will use automated API documentation / swagger etc. usually and not hand-crafted. No?
Either way I can see the vision you you guys have. Being able to see a "diff" of drafts or branches and mapping it to a change request or pull request of code in Github would be fantastic (older Gitbook had it).
Thanks.
It might not be clear yet how the concepts drafts, versions, and revisions interact.
As a quick explanation:
- Revision is our word for commits. One revision is a snapshot of your documentation at a point in time. One revision has a direct parent (or several parents for merge). So revisions easily translate to commits in Git. I don't think we have ever mentioned the term of revision in the UI so far. So this is to make it clear.
- Drafts represent a branching of revisions, they translate to branches in Git. When you start a draft, you create new revisions outside of the main path of revisions. When you publish a draft, you merge the last draft's revision in the current published revision.
- Versions is just a structure above pages, so that your documentation can list different versions of itself. It can be used to document several versions of your product in parallel. Having several versions just duplicates your summary and gives the reader a dropdown to navigate between "versions". The word can be confusing though, because versions have nothing to do with versioning or revision history. A Revision contains the state of your documentation, including the Versions in it.
---
You can see the changes brought by any draft before publishing it, using the diff switch. Changes made on the main version in the meantime are not visible from the draft yet though. That's something we will improve.
The history of the revisions is not yet mature, though available. You won't be able to see the detailed changes, or revert revisions etc. But this is definitely a planned feature. Just know that the complete history of revisions is kept available, as always.
Making changes to the "main version" does not get incorporated in the 'draft' either?
Is it draft? Then what is "new version" for ?
As a reader of published Gitbooks, is there anyway I can know what has been changed in current published version, compared to nearest previously published version?