skyworksinc/.github

Github Templates and Actions

.github's Issues

Release Issue Template

Is your feature request related to a problem? Please describe.

We need to track all the issues to be included in a given release and their status. It would be good to do that systematically.

Describe the solution you'd like

We should add a release issue template with instructions on how to create a release task list of issues.

Describe alternatives you've considered

• Project Boards
  We've tried tracking issues on the project boards but the task lists seem to be helpful and we can still use the task board for larger scale planning.

• Milestones
  Milestones allow you to assign a date to a task which is helpful for releases, but they don't have a way to mark things off as you go. You can include markdown, but the checkboxes can't be checked off when rendered. There is also no way to comment on them. We can just link the release issue to the milestone by attaching it to its corresponding milestone.

Additional context

Add any other context or screenshots about the feature request here.

Proposed Plan of Action

• Create a "release" issue template.
• Add an issue in the IDS repo to document the release process and the release issue template usage on the IDS docs site.

Template Workflow to Update the ids Workflows

Problem Statement

When the template workflows are updated, the updates don't get propagated to all the projects. Manually updating them all would be too time consumung. We need a better way to update each project's workflows.

Proposed Solution

We will create a new template workflow that will update that project's ids workflows with the latest from the .github repo and then commit them back to the master branch.

We will need to be careful to preserve any customization required on the workflows. If we can find a way to avoid having to customize a workflow that would avoid this issue.

Alternatives Considered

• Manually updating: Too time consuming
• Might be able to make a set of actions
• An upcoming feature allows workflows to be called similar to actions which would let me easily break down the workflow and centrally locate the definition of each part.

Proposed Action Plan

1. we'll do this
2. We'll do that
3. Then we'll add tests for this and that.

Automate Release Note Generation

Problem Statement

We currently don't have a good way to track what features are included in the release. We also don't have a good way to communicate the features to users.

Proposed Solution

We plan to have a milestone for each release. This milestone includes a list of issues for that release. It also sometimes includes a short description of the milestone.

Alternatives Considered

• Release Drafter
  • Creates the release notes based off the PRs between tags.
  • Doesn't support milestones
  • Very popular (>2k stars)
• Release Notes Generator
  • Generates release notes based on milestones
  • Gives an example of running it when a milestone is closed.
  • • not as much flexibility & documentation isn't as detailed as other alternatives
  • uses: github-changelog-generator
• generate-changelog-action
• release-notes-generator-action
• generate-changelog-action
• towncrier
  • Discussion from Scipy: scipy/scipy#7793

Proposed Action Plan

• Create release notes using gren based on the issues of the milestone and commit them.
  • https://github.com/lakto/gren-action
  • Only for production releases
• Add the release notes to the GitHub release description
• Send an e-mail announcing the release
  • Send it to the IDS users mailing list

Release Workflow Template

Problem Statement

We have many IDS projects that require release automation so that we can quickly and easily release our projects. This will enable us to release more frequently and receive feedback more regularly.

Each IDS project has similar needs. We should be able to accommodate most projects. We should document any project structure requirements requirements

It needs to be quick and easy to add to a new IDS project. It should also be easy to make minor customizations and parameterizations for each project

Proposed Solution

We will create a template workflow that works for all IDS projects. Each project should only need to make minor customization updates. In many cases these will be limited to the ENV top-level entry

Each "Job" will have its own GitHub Action,

Steps:

• Package 1 or more conda recipes
  • Runs if a conda-recipe folder exists
  • Recipe will run the Python and skill tests
  • Recipe will run the Python and SKILL lint
  • Report the Python and SKILL Lint score
  • Add package(s) to the artifacts
• Release Package
  • Release Conda package to Conda channels (dev or prod)
  • a production or dev version based on run type and input selected.
• Build sphinx docs
  • Created if the "Docs" folder exists
  • Add docs to artifacts
• Release documentation
• Release to GitHub releases
  • See the Skywalker release workflow for an example on how to do that. It will also tag the release with the version number.
• Update Conda environments

IDS Project Structure Requirements:

• "conda-recipe" directory for the Conda recipe.
• Sphinx make file in docs/ folder and a envs/build-docs.yml Conda env definition file

Alternatives Considered

• A single workflow containing the contents of all the actions. This quickly became messy. It also doesn't allow the workflow to be automatically updated.

Proposed Plan of Action

• 1, Create the ids-actions-build-conda action
• 2. Create the ids-actions-build-sphinx-docs action
• 3. Create the ids-actions-release action
• 4. Finish the existing Softworks release script using these actions
• 5. Copy the file to the templates folder.
• 6. Try adding it to datapanels

Resources

• Run workflows locally for development:
  https://github.com/nektos/act
• We'll need to use context and expressions in the workflow:
  https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions