10:57 a.m.
Hey everyone,
Just following up from our discussion point, from the 30th July weekly call, on making a
decision on the repo’s workflow. We are looking to come to a decision on the definition
and implementation from the initial PR to tagging and releasing. I wanted to highlight a
few points we all agreed on during that weekly call:
• We want the ‘main’ branch (will be renamed from the previous ‘master’) to be hub of
activity and the default branch of the repo.
• We want authors initial contributions to be merged into the repo as soon as possible
rather than waiting for the PR to be ‘perfect’.
• We want to tag releases (if possible) to indicate versions of the guidebook e.g.
1.99 or 2.0
So I experimented a bit the past nights and discovered a few things:
• tags are snapshots of a branch’s history, not a selection of files but the tagging
of a particular commit. This mean ALL files (if there is no static website generator at
works here) will be included, some of which could be unpolished chapters.
[https://git-scm.com/book/en/v2/Git-Basics-Tagging]
• We don’t need to use the GitHub publish feature, tags are visible on the ‘releases’
page [https://github.com/samus-aran/super-book-1/releases] but if we use tags for
‘development’ stages then it would be better to deem “releases” as a major release of the
publication.
I have created a repo named “super-book-1” which the ‘main’ branch is the one I merge all
my edits into and my ‘publish’ branch is what I would deem as the finished product.
If I tag my main branch v1.5 then that will include my draft content:
https://github.com/samus-aran/super-book-1/releases/tag/v1.5 GitHub automatically creates
these assets if you’ve tagged a commit.
Since this tag I’ve created a new file/commit which I pushed up to ‘main’ but I also
cherry picked to the publish branch!
Now, unfortunately with selective cherry picking we are picking out commits not files
which leads to the new ‘publish’ branch only having 1 file (the one commit I selected).
I wouldn’t wish my worse enemy to have to cherry pick all the files we ‘deem ready’ for
publish without some sort of identifier on the page itself. Without it we are just combing
the ‘since modified’ between tags without confirmation which page is ready for which
publication release.
So what I suggest at least is we start to identify on the pages themselves (not just
labels on their issues or PRS) what is their current state. This state could simply be
‘draft’.
I also think we should consider what tool we would use to publish the site itself and
whether we need to use an off the shelve static website generator or need to make our own
to handle releases.
Depending on the tools we use to ‘publish’ the repo we can utilise the static generator’s
own filtering to not publish pages if the page meta data states ‘draft’. Examples of these
are:
◦ Hugo: Draft, Future, and Expired Content
[https://gohugo.io/getting-started/usage/#draft-future-and-expired-content]
◦ Jekyll: _drafts folders or draft:true
[https://gohugo.io/getting-started/usage/#draft-future-and-expired-content]
Alternatively we can generate the publish branch ourselves by gathering all the ‘modified’
files since a tag or even branch so we can identify we want “these, these and these” files
if they have been since updated from the last release.
Example is:
zip modified-files.zip $(git diff --name-only publish..main –diff-filter=ACMRT)
This will generate a zipped folder of all the files that have been since modified so at
least we can see the differences between a previous release to now (and also release it as
a asset as another publishing option). Note here, there is a quirk with deleted files but
I know a workaround for this also if we decide to need to do a manual comparison.
In our scenario, we want to selectively choose only the files that aren’t draft and merge
them into the publish branch. In our example that would be all the chapters except
chapter-4… so that would be crawling through those files and gathering all the commits (if
we want to retain the commit history) and cherry picking them (or squashing them) into our
publish branch. It’s doable, but prone to human error. I’ll be honest, I haven’t explored
re-basing or am I an expert in git but I feel git isn’t the right tool for these bulk
selection of files.
So long story short it can be done but I think that having the right publishing tool that
would just simply generate the website (or gather the data) based on each chapter’s
metadata would be the quickest and easiest way for us. This will allow us also to ‘tag’
based on a folder directory or ‘publish’ branch which just stores the published files.
Aside from that static website generator discussion we can have a quick win and identify
that a page is ‘draft’ in it’s metadata similarly to what we do with ‘authors’ and
‘updated’. We don’t need any more statuses than that i.e. if it has no state then it’s
published.
Conclusion, I’m not further forward on a suggestion of the right workflow (beyond using
'main' branch and status draft ) without knowing how we release a complete product
but only provided ‘there is a way’ for either and the details can always be ironed out.
:)
I've asked other OS projects for advice on their documentation process, so I'll
update if there is more that could help.
- Ashley