ga4gh / gh-openapi-docs

Package for building OpenAPI schema docs and UI for gh-pages
Apache License 2.0
7 stars 5 forks source link

Verify that build/deploy works correctly with HubFlow branching model #35

Open jaeddy opened 4 years ago

jaeddy commented 4 years ago

A few of the GA4GH Cloud WS repos strongly encourage use of the Hubflow by contributors. The main impact relevant to this package is the prescribed naming of branches — i.e.:

Create a "feature" branch for each update that you're working on (either in the main repo or your fork depending on the previous step). These branches should start with "feature/issue-[number]-[some-description]". For example "feature/issue-123-improving-the-docs". Most devs will use the HubFlow command line tools to do this however, if you make a feature branch in GitHub's UI, then please make sure you follow this naming convention.

Other branch prefix options include release/ and hotfix/. Nominally, this would result in the branch "type" being an explicit part of the docs URL in GH Pages. That is, instead of https://ga4gh.github.io/<repoName>/preview/issue-123-improving-the-docs/docs it would be https://ga4gh.github.io/<repoName>/preview/feature/issue-123-improving-the-docs/docs.

I want to double check two things:

  1. That I'm not mangling branch names in anyway that would break this URL pattern.
  2. That there aren't any uncaught conditions that would result in unrelated parts of the GH Pages content getting overwritten or deleted by mistake.
tschaffter commented 4 years ago

I'm using Hubflow for one of my repo and have successfully run gh-openapi-docs on a branch named feature/<something>. Note that the openapi specification files and the folder docs have been saved to preview/feature/<something>/. I was positively surprise to see this operation succeed. I haven't reviewed the code yet to understand how gh-openapi-docs interacts with the branch gh-pages of a repo, but at least I can confirm that the documentation was successfully built locally in the case described above.