search

jupyter-server / jupyter_releaser

A set of helper scripts and GitHub Actions to aid in automated releases of Python and npm packages.
https://jupyter-releaser.readthedocs.io/en/latest/
Other
53 stars 66 forks source link

Improve "convert repo" docs #582

Open martinRenou opened 2 months ago

martinRenou commented 2 months ago

I find the https://jupyter-releaser.readthedocs.io/en/latest/how_to_guides/convert_repo_from_repo.html docs page difficult to understand.

Set up a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#github-apps-that-act-on-their-own-behalf) on your organization (or personal account for a personal project).
- Disable the web hook
- Enable Repository permissions > Contents > Read and write
- Select “Only on this account”
- Click “Create GitHub App”
- Browse to the App Settings
- Select “Install App” and install on all repositories
- Under “General” click “Generate a private key”
- Store the APP_ID and the private key in a secure location (Jupyter Vault if using a Jupyter Org)

Missing information from here:

Create a “release” environment on your repository and add an APP_ID Environment Variable and APP_PRIVATE_KEY secret. The environment should be enabled for “Protected branches only”.

This is a bit unclear. Where to find the APP_ID? Should the private key include -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- (yes)? We need to clarify this

Configure Rulesets for the repository Set up branch protection (with default rules) on publication branches Remove global tag protection. Add a branch Ruleset for all branches Allow the GitHub App to bypass protections Set up Pull Request and Required Checks Add a tags Ruleset for all tags Allow the GitHub App to bypass protections

The steps are unclear. I was personally not able to go through this. It seems it's not required though. Should we remove that from the docs or add more information and screenshots?

jtpio commented 2 months ago

where to find how to create a Github app: org settings -> developper settings -> Github Apps -> New Github App button

Right, this should be better documented :+1:

What to provide as Homepage URL?

Most of the Jupyter repos point to https://jupyter.org/. For other repos, maybe the link to the repo or the parent org? We could add some examples of URLs in the docs.

Where to find the APP_ID?

Probably related to the first point. Normally it should be visible on the app settings page, close to where the app was created.

The steps are unclear. I was personally not able to go through this. It seems it's not required though. Should we remove that from the docs or add more information and screenshots?

I guess this is because most of the Jupyter repos have a ruleset configured as best practice. Maybe this step should be optional (but recommended) so it can be skipped for repos that haven't set such ruleset yet?