Aveline-art
commented
1 year ago GitHub Actions Migration Process Proposal
Introduction
This proposal describes the process in which we will migrate our existing GitHub actions scattered across multiple HfLA repos. These actions should, ideally, exist in a centrally maintained place where they can be disseminated across multiple projects.
This proposal has several sections:
- "Development" section: describes a process for how these actions are developed
- "Project Management": describes how this development process can be overseen
- "Requirements": prerequesites that needs to be in place to establish a working pipeline
- "Lingering Questions": items open to discussion
- "My recommendations, in no specific order": what it says on the tin
- "Some Links": loose documentation arranged in no particular order that covers topics brought up in the proposal
Development
Most of the actions at HfLA are used for project management and as such follow a highly predictable template. Therefore to develop our existing actions as repo-based actions, we need to:
- Use a starter template with all the boilerplate needed for an optimal dev environment
- The preexisting actions code is copied over
- The copied code is refactored to fit the repo-based actions framework
- Tests are added to the code
- An org-level workflow template is created to disseminate the action
- The action is documented in its own repository's readme with dev specific info
- The action is documented in a central website with installation specific info
Project Management
Since these migrated actions will be slightly different than the repos we are sourcing them from, we need to utilize a process that can properly quality control them. These are the steps in which these actions will be created and assessed.
- Project Review: Every existing action of interest will be reviewed on what they should ideally do, which could be exactly the same as it currently is. At this stage, we will create criteria for acceptance.
- Development: A developer takes our requirements and the existing code, and create it as outlined in the "Development" section.
- Code Review: A second developer reviews the body of work that makes up this action, including the code, documentation, and org-level template.
- Alpha/Beta Release: The action is released as an alpha/beta version.
- Live Trial: The source of the action will migrate to use the repo-based action, and tested to ensure the action's quality.
- Release: The action is released as a first version.
Requirements
The following are the setup and requirements we need to start this migration process.
Development
- [ ] Starter repo template for actions. The template must include:
- [ ] Boilerplate for github action such as actions.yml
- [ ] Testing library
- [ ] Typescript support for JS actions
- Typescript is preferred over raw JS because it allows typing. This makes development much easier as it is easier to look up the shape of the data sent from the GitHub actions runner.
- [ ] Scripts for quickly calling and getting feedback via GH api
- This allows the developer to do something like say, create an issue quickly, without logging onto github to do so, to testing an issue related action.
- [ ] Instructions on how to use the template after setting up
- [ ] Misc health files or health file templates
- [ ] Central repo to host the documentation website. This repo needs:
- [ ] Project board to manage the project (see "Project Management" below)
- [ ] Procedures for adding a new page to describe our new actions
- [ ] Pipeline to compile and host new documentation
- [ ] .github repo to host the org-level workflow templates
Project Management
- [ ] Procedure to review actions
- [ ] Project board to host issues related to current actions
- [ ] Instructions on how to create alpha/beta/other releases for actions
- [ ] Procedure to assess trial outcomes
- [ ] Procedure on maintaining and improving the action post-release
Lingering Questions
- Where will we host the central repo for the documentation website?
- Where will we host the project board?
- Do we need a separate way of organizing bug fixes/improvements to migrated actions?
- Do we need to personally setup the GHAs for our stakeholders?
- What framework will we use to create our documentation website?
- What kind of team do we need to maintain the documentation repo?
- Do we need project managers, designers, researchers?
- Should there be a separate gha-development team and a documentation repo team?
- How will we advertise our actions?
My recommendations, in no specific order
- Use the .github repo to store workflow templates
- Be aware that this will make it nonviable as a template repository because the workflow templates follow a specific format that should not be copied over to a new repo
- Use the engineering repo to:
- host the documentation website
- Use Docusaurus to create a static website hosted on gh-pages
- host our project board
- Have issue templates (in engineering) for:
- Proposing a GHA (should be lightweight, compared to 100 auto's template)
- Bug fixes and improvements
- Issues related to creating and improving the documentation website
- Have one repo for our actions template
- Have a separate gha dev-team, and a documentation repo team, which may or may not have overlapping members
- The actions we create are in an opt-in basis; a team member (of any role) can choose to add them if they so wish
Some Links
- Sample Template, and Sample Migrated Repo
- Docusaurus docs
- GHA docs
- Org-level workflow template: Create, Use
- JS Actions
- Interesting stuff that is not useful at the moment, but damn is this interesting and awesome:
- https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile
- https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization
- https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization
- https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file
ExperimentsInHonesty
Overview
In order to migration our GitHub Actions from a repo level to a org level, we need to figure out how this process will work. For this issue, we will create, review, and approve a proposal for this migration.
Action Items
Resources/Instructions