Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Workflows for creating releases with docs #891

Open
wants to merge 11 commits into
base: v3
Choose a base branch
from
Open

Conversation

taras
Copy link
Member

@taras taras commented Feb 9, 2024

Related #890

Motivation

This PR introduces two GitHub Actions Workflows:

  • create-release.yaml
  • rebuild-releases.yaml

create-release.yaml

This workflow runs anytime a tag is created that matches "effection-v*". It'll checkout the tag, generate docs with deno doc, create a tarball and create a release.

rebuild-releases.yaml

This workflow can only be triggered manually. It can be used to rebuild all of the releases. It has two jobs: setup & rebuild. The setup job gets a list of all tags that match the "effection-v*" pattern and sticks the result into outputs. The rebuild job uses outputes from setup as matrix. The actual workflow is same as create-release.yaml

TIL

  1. GitHub has a new mechanism for managing tokens generated by users in an organization. If you want to interact with an organization's resources, you'll need to create a token specifically for that organisation. There are additional configuration options under TheFrontside github org settings
  2. You can have dynamic matrixes in GitHub Actions at the bottom of the blog post there are good examples like this one
  3. act -s GITHUB_TOKEN="<YOUR_TOKEN>" -W .github/workflows/rebuild-releases.yml workflow_dispatch can be used to run rebuild-releases.yaml on your machine

TODO

  • How do I test this?
  • How do I run this for all existing tags?

@taras taras requested a review from cowboyd February 9, 2024 23:28
Copy link
Member

@cowboyd cowboyd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a huge fan of having workflows commit directly to the main branch. Why not just create a release associated with the tag that contains the docs and make the docs part of the release?

If we want to go the route of having our workflows commit to the repository, then I think it should be part of a "merge release" which pushes to a release branch, and then contains

  • changelogs
  • docs

Then that thing gets tagged.

However, if our website needs to be able to switch between API docs versions, then it doesn't make sense to have it in the repository.

@taras
Copy link
Member Author

taras commented Feb 10, 2024

Using a release is a good idea and it might be easier. I'll do that

@taras taras changed the title Added workflow to push docs to tag Workflows creating releases with docs Feb 10, 2024
@taras taras changed the title Workflows creating releases with docs Workflows for creating releases with docs Feb 10, 2024
@taras taras requested a review from cowboyd February 10, 2024 23:43
Copy link
Member

@cowboyd cowboyd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: Do we need the rebuild releases? At the most, it seems like we would need them for 3.0.0, 3.0.1, and 3.0.2

.github/workflows/create-release.yml Outdated Show resolved Hide resolved
@taras
Copy link
Member Author

taras commented Feb 12, 2024

Do we need the rebuild releases? At the most, it seems like we would need them for 3.0.0, 3.0.1, and 3.0.2

I guess that's true. I was thinking in case we want to update the releases to a specific format. Like now, I need to rerun, to rebuild at least 3.0.0, 3.0.1 and 3.0.2. In the future, there will be more. I can change the filter to only include non-preview releases.

What do you think?

@cowboyd
Copy link
Member

cowboyd commented Feb 12, 2024

Do we need the rebuild releases? At the most, it seems like we would need them for 3.0.0, 3.0.1, and 3.0.2

I guess that's true. I was thinking in case we want to update the releases to a specific format. Like now, I need to rerun, to rebuild at least 3.0.0, 3.0.1 and 3.0.2. In the future, there will be more. I can change the filter to only include non-preview releases.

What do you think?

I'm torn, on the one hand, I feel like releases are releases, and that means a binary artifact corresponding to a specific git SHA. On the other, you're right. What if we need to update urls, or change style?

In that case, maybe it's best to have an executable task in the repo that we can do manually?

@taras
Copy link
Member Author

taras commented Feb 12, 2024

In that case, maybe it's best to have an executable task in the repo that we can do manually?

The setup I have allows us to rerun the job via GitHub UI. Would you like me to rewrite it to Deno?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants