Comments on the adoption guide

[krassowski]

There are small bits I found unclear and would like to ask for clarification:

Bump version configuration (if using Python), for example tbump

thbump is mentioned as optional here, but the rest of the guide seems to suggest it is required for Python; it does not explain what API should be exposed by alternatives. It is also not clear how node package version bumping is handled.

Add a GitHub Access token with access to target GitHub repo to run GitHub Actions, saved as ADMIN_GITHUB_TOKEN in the repository secrets

Which permissions are needed for this token? Does it have to be a PAT token (which AFAIK cannot be scoped per repo), or can we use a deploy key?

Add a GitHub Actions CI step to run the check_release action

Where? In which job it should be contained? What does this action do?

Update or add RELEASE.md that describes the onboarding and release process, e.g.

The example is missing? I guess a link is missing?

We recommend putting setuptools metadata in setup.cfg and using version attr: <package_name>.__version__, see example setup.cfg

Nitpick: version = attr: <package_name>.__version__

[welcome]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively.

You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[jtpio]

Thanks @krassowski for opening 👍

Answering here for now but this should eventually go the documentation.

thbump is mentioned as optional here, but the rest of the guide seems to suggest it is required for Python; it does not explain what API should be exposed by alternatives. It is also not clear how node package version bumping is handled.

Right jupyterlab uses bump2version. Also for npm it's the npm version command which works fine when there is a single package.json at the top level:

jupyter_releaser/jupyter_releaser/util.py

Lines 195 to 231 in 25f51b4

	def bump_version(version_spec, version_cmd=""):
	"""Bump the version"""
	# Look for config files to determine version command if not given
	if not version_cmd:
	for name in "bumpversion", ".bumpversion", "bump2version", ".bump2version":
	if osp.exists(name + ".cfg"):
	version_cmd = "bump2version"
	if osp.exists("tbump.toml"):
	version_cmd = version_cmd or TBUMP_CMD
	if PYPROJECT.exists():
	if "tbump" in PYPROJECT.read_text(encoding="utf-8"):
	version_cmd = version_cmd or TBUMP_CMD
	if SETUP_CFG.exists():
	if "bumpversion" in SETUP_CFG.read_text(encoding="utf-8"):
	version_cmd = version_cmd or "bump2version"
	if not version_cmd and PACKAGE_JSON.exists():
	version_cmd = "npm version --git-tag-version false"
	if not version_cmd: # pragma: no cover
	raise ValueError("Please specify a version bump command to run")
	# Assign default values if not version spec was given
	if not version_spec:
	if "tbump" in version_cmd:
	version = parse_version(get_version())
	version_spec = f"{version.major}.{version.minor}.{version.micro + 1}"
	else:
	version_spec = "patch"
	# Bump the version
	run(f"{version_cmd} {version_spec}")
	return get_version()

For more complex layouts like JS and / or Python monorepos, it's preferable to have a custom version-cmd.

Which permissions are needed for this token? Does it have to be a PAT token (which AFAIK cannot be scoped per repo), or can we use a deploy key?

We could add the following screenshot to the docs:

Where? In which job it should be contained? What does this action do?

It can be in an existing workflow. Or in a dedicated one (better so it can be restarted and debugged more easily). For example: https://github.com/jupyter/notebook/blob/master/.github/workflows/check-release.yml

The example is missing? I guess a link is missing?
Nitpick: version = attr: <package_name>.__version__

Good catch! Mind opening a PR? Thanks!

[krassowski]

How do I change the version command? It is by adding

[tools.jupyter-releaser.options]
version_cmd = "myversionbump"

to .jupyter-releaser.toml? I guess my point is that /latest/reference/configuration.html is empty ("Coming soon") and beside latest/how_to_guides/write_config.html I don't know which of the CLI arguments translate to the config options...

After spending more time looking at the code I guess all?

Currently a user can only learn the answer by reading the code in depth and learning how click integration works in:

jupyter_releaser/jupyter_releaser/cli.py

Lines 17 to 121 in 1bc9790

	class ReleaseHelperGroup(click.Group):
	"""Click group tailored to jupyter-releaser"""
	_needs_checkout_dir = dict()
	def invoke(self, ctx):
	"""Handle jupyter-releaser config while invoking a command"""
	# Get the command name and make sure it is valid
	cmd_name = ctx.protected_args[0]
	if not cmd_name in self.commands:
	super().invoke(ctx)
	if cmd_name == "list-envvars":
	envvars = dict()
	for cmd_name in self.commands:
	for param in self.commands[cmd_name].params:
	if isinstance(param, click.Option):
	if param.envvar:
	envvars[param.name] = param.envvar
	for key in sorted(envvars):
	util.log(f"{key.replace('_', '-')}: {envvars[key]}")
	return
	orig_dir = os.getcwd()
	if cmd_name.replace("-", "_") in self._needs_checkout_dir:
	if not osp.exists(util.CHECKOUT_NAME):
	raise ValueError("Please run prep-git first")
	os.chdir(util.CHECKOUT_NAME)
	# Read in the config
	config = util.read_config()
	hooks = config.get("hooks", {})
	options = config.get("options", {})
	skip = config.get("skip", [])
	if "--force" in ctx.args:
	skip = []
	ctx.args.remove("--force")
	skip += os.environ.get("RH_STEPS_TO_SKIP", "").split(",")
	# Print a separation header
	util.log(f'\n\n{"-" * 50}')
	util.log(cmd_name)
	util.log(f'{"-" * 50}\n\n')
	if cmd_name in skip or cmd_name.replace("-", "_") in skip:
	util.log("*** Skipping based on skip config")
	return
	# Handle all of the parameters
	for param in self.commands[cmd_name].get_params(ctx):
	# Defer to env var overrides
	if param.envvar and os.environ.get(param.envvar):
	continue
	name = param.name
	if name in options or name.replace("_", "-") in options:
	arg = f"--{name.replace('_', '-')}"
	# Defer to cli overrides
	if arg not in ctx.args:
	val = options.get(name, options.get(name.replace("_", "-")))
	if isinstance(val, list):
	for v in val:
	ctx.args.append(arg)
	ctx.args.append(v)
	else:
	ctx.args.append(arg)
	ctx.args.append(val)
	# Handle before hooks
	before = f"before-{cmd_name}"
	if before in hooks:
	before_hooks = hooks[before]
	if isinstance(before_hooks, str):
	before_hooks = [before_hooks]
	if before_hooks:
	util.log(f"\nRunning hooks for {before}")
	for hook in before_hooks:
	util.run(hook)
	# Run the actual command
	super().invoke(ctx)
	# Handle after hooks
	# Re-read config if we just did a git checkout
	if cmd_name in ["prep-git", "extract-release"]:
	os.chdir(util.CHECKOUT_NAME)
	config = util.read_config()
	hooks = config.get("hooks", {})
	after = f"after-{cmd_name}"
	if after in hooks:
	after_hooks = hooks[after]
	if isinstance(after_hooks, str):
	after_hooks = [after_hooks]
	if after_hooks:
	util.log(f"\nRunning hooks for {after}")
	for hook in after_hooks:
	util.run(hook)
	os.chdir(orig_dir)

Ideally jupyter-releaser could be adopted without having to extensively read its codebase. But since I am already here, shouldn't:

jupyter_releaser/jupyter_releaser/lib.py

Lines 294 to 297 in 1bc9790

	# Read in the config
	config = util.read_config()
	options = config.get("options", {})
	npm_install_options = npm_install_options or options.get("npm-install-options", "")

first convert from _ to -? If I read it correctly or options.get("npm-install-options", "") will only work for JSON config but not for toml and friends.

[krassowski]

And by the way thanks for the quick reply @jtpio. Sorry it took me a while to get back to it, but I'm hoping to get a release of LSP extension out using jupyter-releaser this week(end).

[jtpio]

@krassowski just checking if this is still an issue with Releaser v2 or if there are remaining items that should be tracked here or separately? Thanks!