Metadata-Version: 2.4
Name: strawberry-autopub-plugins
Version: 0.3.0
Summary: AutoPub plugins maintained by Strawberry GraphQL
Author: Strawberry GraphQL
License: MIT
Requires-Python: >=3.10
Requires-Dist: autopub<2.0.0,>=1.0.0a58
Description-Content-Type: text/markdown

# strawberry-autopub-plugins

AutoPub plugins maintained by Strawberry GraphQL.

## Included plugins

- `InviteContributorsPlugin` (`strawberry_autopub_plugins.invite_contributors:InviteContributorsPlugin`)
  - Invites pull request contributors to a GitHub organization after `autopub publish`.
  - Can also add invited users to a GitHub team.
- `TypefullyPlugin` (`strawberry_autopub_plugins.typefully:TypefullyPlugin`)
  - Creates Typefully drafts or scheduled posts for release announcements.
  - Supports per-platform templates for `x`, `linkedin`, `threads`, `bluesky`, and `mastodon`.

## Installation

```bash
pip install strawberry-autopub-plugins
```

## Usage

Add one or more plugin paths to your AutoPub config:

```toml
[tool.autopub]
plugins = [
  "poetry",
  "github",
  "strawberry_autopub_plugins.invite_contributors:InviteContributorsPlugin",
  "strawberry_autopub_plugins.typefully:TypefullyPlugin",
]
```

Plugin config is keyed by each plugin's `id`:

- `invite_contributors`
- `typefully`

## InviteContributorsPlugin

Plugin path:

```text
strawberry_autopub_plugins.invite_contributors:InviteContributorsPlugin
```

Environment variables used when the plugin needs to call the GitHub API:

- `GITHUB_TOKEN`
- `GITHUB_REPOSITORY`

Optional environment variables:

- `GITHUB_EVENT_PATH`

`GITHUB_TOKEN` must be able to invite users to the target organization.

Example config:

```toml
[tool.autopub.plugin_config.invite_contributors]
organization = "strawberry-graphql"
team-slug = "strawberry-contributors"
role = "direct_member"
skip-bots = true
include-co-authors = true
exclude-users = ["renovate[bot]"]
dry-run = false
```

Options:

- `organization`: Target GitHub organization. If omitted, the plugin falls back to the repository organization.
- `team-slug`: Optional team slug to add invited contributors to.
- `role`: One of `direct_member`, `admin`, or `billing_manager`. Default: `direct_member`.
- `skip-bots`: Skip logins ending in `[bot]`. Default: `true`.
- `include-co-authors`: Include `Co-authored-by:` trailers found in commit messages. Default: `true`.
- `exclude-users`: Additional usernames to skip. Defaults to `dependabot-preview[bot]`, `dependabot-preview`, `dependabot`, and `dependabot[bot]`.
- `dry-run`: Print which users would be invited without sending invitations. Default: `false`.

## TypefullyPlugin

Plugin path:

```text
strawberry_autopub_plugins.typefully:TypefullyPlugin
```

Environment variables used when the plugin needs to create a Typefully draft:

- `TYPEFULLY_API_KEY`

Optional environment variables:

- `TYPEFULLY_SOCIAL_SET_ID`

You can provide the social set ID either through `social-set-id` in config or `TYPEFULLY_SOCIAL_SET_ID`.
In `dry-run` mode, the plugin can render the request body without requiring either value.

Example config:

```toml
[tool.autopub.plugin_config.typefully]
social-set-id = "abc-123"
platforms = ["x", "linkedin", "bluesky"]
project-name = "Strawberry"
message-template = "{project_name} {version} has been released!\n\n{release_notes}"
publish-mode = "draft"
tags = ["release", "python"]
require-social-message = true
required-social-platforms = ["x", "linkedin"]
required-message-substrings = { x = ["https://example.com/releases/{version}"] }
require-release-note-lead = true
truncation-suffix = "..."
dry-run = false

[tool.autopub.plugin_config.typefully.platform-templates]
x = "{project_name} {version} is out now.\n\n{release_notes}\n\nhttps://example.com/releases/{version}"
linkedin = "{project_name} {version} has been released.\n\n{release_notes}"

[tool.autopub.plugin_config.typefully.platform-max-lengths]
linkedin = 3000
```

Options:

- `social-set-id`: Typefully social set to post into. Required unless `TYPEFULLY_SOCIAL_SET_ID` is set.
- `platforms`: Platforms to enable. Supported values: `x`, `linkedin`, `threads`, `bluesky`, `mastodon`. Default: `["x"]`.
- `message-template`: Default template for all platforms. Default: `{project_name} {version} has been released!\n\n{release_notes}`.
- `platform-templates`: Per-platform template overrides.
- `project-name`: Value exposed to templates as `{project_name}`.
- `publish-mode`: One of `draft`, `now`, `next-free-slot`, or `scheduled`. Default: `draft`.
- `publish-at`: Required when `publish-mode = "scheduled"`.
- `tags`: Optional Typefully tags to attach to the draft.
- `require-social-message`: Require release notes to include `social_message` or `social_messages` frontmatter before publishing. Default: `false`.
- `required-social-platforms`: Platforms that must have `social_messages` entries when `require-social-message` is enabled. Defaults to all configured `platforms`.
- `required-message-substrings`: Per-platform substrings that must appear in the rendered post. Substrings use the same template variables as messages and are checked after truncation, so missing or truncated links fail before publishing.
- `require-release-note-lead`: Require release notes to start with an approved user-facing lead. Default: `false`.
- `release-note-leads`: Approved release note prefixes. Defaults to `This release adds ` and `This release fixes `.
- `max-length`: Optional maximum post length before truncation for all platforms.
- `platform-max-lengths`: Per-platform maximum post lengths. Defaults are `x = 280`, `linkedin = 3000`, `threads = 500`, `bluesky = 300`, and `mastodon = 500`.
- `truncation-suffix`: Suffix appended after truncation. Default: `...`.
- `dry-run`: Print the request body without calling the Typefully API. Default: `false`.

Template variables:

- `{project_name}`
- `{version}`
- `{release_type}`
- `{release_notes}`: release notes converted to social-friendly plain text.
- `{release_notes_plain}`: alias for `{release_notes}`.
- `{release_notes_markdown}`: raw Markdown release notes.
- `{previous_version}`

Release-specific override from `RELEASE.md` frontmatter:

```md
---
release type: patch
social_message: |
  Strawberry {version} is out now.

  Highlights:
  {release_notes}
---

- Fixed X
- Added Y
```

When `social_message` is present in AutoPub frontmatter, the plugin uses it as the message template for all configured platforms and still expands the same template variables listed above.

You can also override individual platforms from frontmatter:

```md
---
release type: minor
social_message: |
  Strawberry {version} is out.

  {release_notes}
social_messages:
  linkedin: |
    Strawberry {version} is out.

    This release adds a larger LinkedIn-specific announcement.

    {release_notes}
---

- Added X
- Fixed Y
```

Platform-specific frontmatter overrides take precedence over `social_message`,
which takes precedence over configured `platform-templates`.

## Development

```bash
uv sync
uv run pytest
```

When changing dependencies, update the lockfile:

```bash
uv lock
```
