Metadata-Version: 2.4
Name: splent_feature_github
Version: 0.1.0
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Dynamic: license-file

# splent_feature_github

The `github` feature of a [SPLENT](https://splent.io) product line.

Sign in and sign up with GitHub, and connect a GitHub account to an account
from its profile. A new account takes the email GitHub shares, or else the
verified primary address of the GitHub account, and the name it gives. A
GitHub account always signs in to the account it is linked to, and never to
an existing account because the email matches. It needs `auth`, `profile`
and `identities`, which keeps the linked accounts and the shared OAuth
registry.

A SPLENT feature is a Python package that a product composes with others.
Its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
`[tool.splent.contract]` section of `pyproject.toml`, which
`splent feature:contract --write` keeps in sync with the source.

## Settings

| Setting | Default | What it is |
|---|---|---|
| `GITHUB_CLIENT_ID` | empty | The client id of the OAuth app registered at https://github.com/settings/developers |
| `GITHUB_CLIENT_SECRET` | empty | Its secret |

Without both, GitHub sign-in fails with a message and the app logs a warning
at startup.

## Where it shows

It fills the slots other features open, by name, so it composes with
whatever the product has and overrides nothing.

| Slot | Opened by | What GitHub draws |
|---|---|---|
| `auth.login.providers` | auth | The GitHub button, under "or continue with" |
| `signup.providers` | signup, when the product has it | The same button, after the sign-up form |
| `profile.edit.sections` | profile | The linked account with a disconnect button, or a "Connect GitHub" link |
| `layout.head.css` | the product's app shell | Its stylesheet, `assets/css/github.css` |

It takes order 10 in the first three, before ORCID's 20. The button carries
where the reader was heading (`?next=`), and only a path on this site. The
disconnect button opens identities' modal.

GitHub's dark grey is in `assets/css/github.css`, never on the elements. The
public shell loads the file from the asset registry (`register_asset`), and
the app shell, which does not render the registry, through
`layout.head.css`. A product that wants another look overrides
`.btn.btn-github` and the `github-identity__*` classes in a stylesheet of its
own.

## A product without signup

A product that does not install `splent_feature_signup` is closed, and its
accounts are opened by an administrator. GitHub follows the rule identities
holds for every provider.

| Visitor | With signup | Without signup |
|---|---|---|
| Signs in with a GitHub account already linked | Signed in | Signed in |
| Connects GitHub from their profile | Linked | Linked |
| Signs in with a GitHub account linked to nobody | A new account is opened | Sent back to the login page with a translated message that asks them to request access from an administrator, or to connect GitHub from their profile if they have an account |

## Translations

The edit-profile row ships with a Spanish catalog.

## Use it in a product

```bash
splent feature:add splent_feature_github
```

## Develop

```bash
splent feature:test splent_feature_github
splent feature:contract splent_feature_github
```

## Release

```bash
splent feature:release splent_feature_github --dry-run --bump patch
splent feature:release splent_feature_github
```

The first command rehearses the release and changes nothing. The second
publishes it to the git forge and to PyPI, and a PyPI version is permanent.
