Gitbook - github sync

đź“ť Documentation
1

I accessed Hypha docs today to show ARDC folks some pages that might be useful and the pages I know I had created did not show up on docs.hypha.app.

Further exploration into the issue indicates that this commit to the docs repository is responsible. It looks like gitbook-bot deleted and moved several pages, and I’m not sure why. For instance, the text of the main README page is gone, and it looks like the file organization, folder structure, and SUMMARY.md file were updated in ways that made some pages inaccessible–maybe rolled back to an older version?

I’d like to roll back to a previous state, which I think I can do it gitbook, but I also see @frjo had another commit 7 days ago that changed some developer setup files related to the switch from gulp to webpack.

@frjo, are you okay with me saving the changes you made in this commit, rolling back, and then resubmitting these changes?

@Maintainers, anyone have ideas regarding how this happened and how to prevent it going forward? Is it a difference between editing within Gitbook vs syncing an old file structure directly to Github from one’s local repository? I want to make sure we include whatever information is relevant to this in the “Contributing to documentation” page, so that this doesn’t happen again in the future.

2

I will revert that commit and bring back the pages.

3

I have now brought back the “understandlearnmore/" and "staff/” pages. Are there more?

4

Yes, the Workflows and Navigation page (under Staff → create user) had content that I can find if I look at the gitbook history (but I can’t figure out how to restore that content).

Also the main “Getting Started” page used to have content (it used to be the main README.md file in the docs repo).

There may be more pages–I can create a list.

Another issue is that the github repo organization no longer matches the structure in Gitbook - I had edited the folder structure and file names in github directly to match Gitbook (about 3 weeks ago now). Some folders that I had deleted or renames are back/in the wrong place/have old names (e.g. maintenance, contributing, deployment).

How/where are you reverting the commits? I ask because

  1. I wonder if there is some weird behind-the-scenes thing going on with Gitbook, or some other commit/push path that is causing this weirdness.
  2. I want to be able to restore deleted pages that I had created on my own (so you don’t need to do it)
5

I have now reverted the repo to before the problematic commit.

I will now add back my changed to the dev pages.

I do all my work directly with git.

6

Dev pages updates in place again.

7

Thanks, things look mostly back to what I remember now (at least in terms of content and structure I added). There are still some files/folders I know I deleted that are back, but I can re-delete them.

@frjo you said:

I do all my work directly with git.

Does this mean you’re pulling and pushing from the main remote repo to a local copy on your machine? Just wondering whether something about doing that plus me working in Gitbook is messing with the Github repo organization.

8

Yes. That is how git normally is used.

With git and other modern versioning systems all versions of the repo is the same, they are “distributed”. This includes the version we host on GitHub.com.

The only special about it is that all devs have agreed that that is the place where everyone push their code for others to see it.

I do not know how the repo got so messed up. My guess would be that Gitbook do not like that one edit in Gitbook and in the repo directly at the same time.

It is certainly possible that I did a blunder as well.

9

I think this is the problem as well. I’d just like to think about whether there is a way to stop something like this from happening again (like maybe we ask that folks only make changes to the documentation using Gitbook).