Onboarding Into A New Github Repo – Initial Commit Actioned PRs

One of the blockers to folk using Github, I think, is the perception that it’s hard and requires lots of command line foo. That is, and isn’t true: you can get started very easily just by addign and editing files via the web (eg Easy Web Publishing With Github).

A new template repo, fastai/fastpages, from the fastai folk uses Github Actions to manage an automated publishing workflow that generates a blogsite, using Github pages, from notebooks and markdown files.

Actually, this is a better repo to use maybe? fastai/fast_template Could still do with some more babysteps explanation about what the _config.yml is and does, for example?

The automation requires a secret to be set as part of the repo settings to allow Github Actions to push generated files the branch that’s actually used to publish the resulting website.

Trying to write instructions that a novice can follow to set up the repo can be a bit fiddly, but the fastai have an interesting take on that: the template also includes a “first run” / “inital commit” action that makes a PR into your cloned repository telling you how to proceed, and providing direct links to the pages on which you need to edit your own settings.

A few moments after your cloned repo is loaded, refresh it, and you should see at least one pull request (PR).

My screenshot actually shows two automated PRs have been made: as well as the fastai on-boarding PR, a Github bot has spotted a vulnerability in a dependency and made its own PR to fix it.

The fastai PR provides instructions, and direct links to pages you need to access, to set up the repo:

There’s still the issue of directing the novice user to the PR page (the repo home page, as created, will show 0 PRs initially: it doesn’t refresh itself to show the updated PR count automatically, I don’t think?) and then how to merge the PR. [Downes also commented on the instructions and tried to make them even more baby steps followable here.)]

But the use of the initial commit triggered PR to stage the presentation of instructions is an interesting onboarding mechanic, I think, and one I might add to some of my own template repos.