Complete GitHub Source-Control

[Malix-Labs]

Feature Request

Make GitBook be able to use GitHub full Source-Control capabilities

Exemples

• Pull Requests
• Branching
• Commit messages with auto-closing words

Importance

• Critical
• High
• Medium
• Low

[alfonsop123]

Huh

[ahcsco]

Tech writers use Gitbook to avoid Git and it's unnecessary complexity in first place. Not sure what is the goal here, but Gitbook should not become another git tool.

[Malix-Labs]

Tech writers use Gitbook

Lol what?
They use it to write docs fast, that's it.
Git has good collaboration tools, you just don't know how to use them

[ahcsco]

Well you said yourself tech writers use Gitbook to write docs fast. There's a reason they use it like that. I've used Git dependent and non-Git dependent docs for several years, and It doesn't matter if i know them or not. What matters is the target audience that Gitbook primarily targets - it's tech writers. Git has a tendency to unnecessarily complicate the documentation process. Besides all these options are anyway available when you integrate towards Github and gitLab.

[Malix-Labs]

Just make it a POSSIBILITY, not mandatory.
You surely hasn't worked in a project where complex collaboration through git is needed

[ahcsco]

Yes. As long as it's optional to use, i'm in.
I work with docs-as-code all the time with dev teams, i have a pretty good idea of it. You seem to be seeing it from developer's angle only. Typical. Avoiding complex (and unnecessary) collaboration of development, is THE very reason why tools like Gitbook, Paligo, Madcap, etc. exist in first place. Good day.

[emmerich]

Hey @Malix-Off, I'm keen to learn more about what you're looking to do. One of GitBook's goals is to bring the best bits of Git and GitHub (change requests where reviews and diffing can take place, full version history, better support for async workflows) to traditional content, all whilst making it understandable and usable for non-tech folks.

For pull requests and branching, we have change requests (that have subjects which are your commit messages in Git). GitBook has a full version history and we allow users to rollback and diff different versions of their content.

If I've understood your feature request correctly, you're looking for ways to tie more of GitBook's concepts to GitHub? So, you could link a pull request in GitHub to a change request in GitBook (and get all the benefits like synced commit messages)?

[jalaziz]

I was just testing the Git sync and was actually surprised GitBook didn't create a GitHub PR. It would be nice for the GitBook CR to be tied to a GitHub PR (and vice versa) allowing developers and technical writers to review the changes using their tool of choice.

I can totally understand how quickly that could get out of hand though. For example, it would be nice to sync comments too, but that adds extra complexity.

One thing that is quite problematic with the Github sync though is how GitBook change request numbers conflict with Github issue and PR auto-linking. I submitted #69 with some points of feedback around the commit message format.

[emmerich]

Absolutely. It's more a historical thing - the Git Sync existed a long time before change requests, and we wanted to properly understand the use-case before tying the two together. As you mentioned - it could get messy (we don't want to create GitBook change requests for code-only changes, for example).

Having said that, we are increasingly seeing this request: being able to link GitBook CRs to things (whether it's PRs in GitHub, GitHub Issues, JIRA tickets, ...) so it's definitely something we're looking at.

Thanks for that suggestion on commit messages - we'll definitely start looking at that and how we can improve workflows that involve both GH and GB.

[steebchen]

Agreed with this, it's good to double check and review using traditional git dev. It also prevents something going wrong and you could potentially run some checks (like grammer checking) to the PRs.

For example, when I first committed using gitbook, it generated this commit but it deletes the CONTRIBUTING.md for some reason. If it had been a live repo, the commit would be now there forever. If it had been a PR, the PR could have been simply rejected.

[thefuntastic]

The current workflow makes adoption within an existing team/tooling difficult.

CR workflow basically creates an entire alternate pathway that exists as an island outside our PR pipeline. A PR pipeline that has a lot of tooling and investment built on top of it. PRs aren't just about code review, they are used at the unit for continuous integration, automated testing, project management, slack automation and notifications.

Sure, one can argue that technical writers don't want to be exposed to git, but our team has 0 technical writers and 50+ developers. The ease of use of gitbook would be a win for those developers, but the fact that we can't use our existing pipeline for documentation makes it very hard to sell to our CTO.