💌📯 Updates

[gr2m]

If you are interested in @octoherd, you can subscribe to this discussion. I'll post comments with project updates.

I've locked the discussion in order to reduce noise. If you have any questions or feedback, please create a separate discussion.

About myself 👋

Hello there, I’m Gregor!

I’m (co-)maintaining a few other JavaScript/Node projects such as @octokit, @probot, @semantic-release, @nock, and @all-contributors. I’m passionate about welcoming and inclusive communities and see it as main responsibility to encourage and support contributions of all kind. You can follow me on Twitter: @gr2m

[gr2m]

Live on TV

@bdougie invited me to talk about @octoherd on GitHub's Open Source Friday Virtual Meetup. I've walked through the Sync Branch Protections script.

Since the live coding session with Brian, the way an @octoherd script is run changed, which brings us to

📰 News

• The octoherd/scripts repository no longer exists. I renamed it to https://github.com/octoherd/octoherd/. All the scripts live in their own dedicated repositories now, you can find them under the octoherd-script topic. I created a script to extract the folders into their own repositories (of course): github.com/octoherd/script-create-repositories-from-script-folders

• A script can now be run directly using npx. For example, in order to run the Sync Branch Protection script, you needed to checkout the scripts repository first and then run @octoherd/cli using npx

  git clone https://github.com/octoherd/scripts.git
  npx @octoherd/cli \
    --octoherd-token 0123456789012345678901234567890123456789 \
    scripts/sync-branch-protections/script.js \
    "octoherd/*" \
    --template "octoherd/cli"

  Now any script can depend directly on @octoherd/cli and export their own binary, which simplifies the way to run it

  npx @octoherd/script-sync-branch-protections \
    --octoherd-token 0123456789012345678901234567890123456789 \
    script-sync-branch-protections/script.js \
    "octoherd/*" \
    --template "octoherd/cli"
  

  I created yet another script to help me with the migration of the existing scripts: https://github.com/octoherd/script-add-octoherd-cli-to-script

• An Octoherd Script no longer need to install @octoherd/octokit and @octokit/openapi-types as dev dependencies. @octoherd/cli exports all relevant types

  /**
  - * @param {import('@octoherd/octokit').Octokit} octokit
  + * @param {import('@octoherd/cli').Octokit} octokit
  - * @param {import('@octokit/openapi-types').components["schemas"]["repository"]} repository
  + * @param {import('@octoherd/cli').Repository} repository
    */

🔜 What's next

• I want to make it simpler to create and share @octoherd scripts. My idea is to create an create-octoherd-script package similar to github.com/octokit/create-octokit-project.js/. It will walk through the creation of the repository and all needed files. It should reduce the amount from idea to published script by several minutes and make the whole process much less error prone than good old copy&paste
• I want scripts to define options that are specific to the script. This will allow the CLI and what ever runner the future brings a (better) way to verify options before the script is even run. I'm intrigued by superstruct and will experiment if it's good fit to define script options. I like the API and the fact that we that the option types can be inferred easily.

👋🏻 Contributions welcome

I'm adding a pull request welcome label to issues that are ready for the taking, here are the current issues that are up for taking.

I really enjoy working on @octoherd. We can take full advantage of Node's support for ES Modules, no build steps are required. And once we get Deno support and implement a web runner, the scripts can be loaded directly from https://skypack.dev/. I'm looking forward to taking full advantage of the fact that the code will just run in all these environments out of the box.

[gr2m]

Here we go again

Not that I've been planning for this, but @bdougie shared another live coding session with @octoherd just as I wanted to post a new update, so there you go. The video is not edited yet, you can start watching at about 1h. Brian is starting from scratch at npm init octoherd-script and then creates a script to copy labels from one repository and apply them to any other repository. Thanks @bdougie, I learned a lot myself 👊🏼

And, since it's tradition, @octoherd changed again since Brian's live coding session, which brings us to ...

📰 News

• Creating a new script is now as simple as running npm init octoherd-script. It does a ton of things for you

  • Creates a new folder on your machine
  • Inits git in the new folder
  • Add LICENSE, CODE_OF_CONDUCT.md and README.md files
  • Prompts for script options and adds according documentation to the README.md file
  • Creates a repository
  • Adds repository as git remote add origin <url>
  • Push the 3 files to main
  • Creates a new local branch called initial-version
  • Creates a package.json and package-lock.json. Installs dev dependencies.
  • Creates .gitignore, tsconfig.json
  • Creates test/smoke.test.ts
  • Creates GitHub Actions for tests and automated releases for GitHub and npm
  • Creates a pull request with further instructions
  • Adds branch protection

• We released version 3 of @octoherd/cli which introduced one breaking change:

  The repository patterns can no longer be passed as positional argument. Instead you have to use the --octoherd-repos flag instead (or -R for short).

  More importantly, version 3 introduced several great improvements which makes it easier than ever to run an @octoherd script.

  1. You no longer need to pass any flags. For example, to run the @octoherd/script-hello-world script, you needed to do the following

     npx @octoherd/script-hello-world \
       --octoherd-token 0123456789012345678901234567890123456789 \
       "octoherd/*"
     

     Now all it takes is

     npx @octoherd/script-hello-world
     

     The CLI will prompt the user to create a token using GitHub's Device Flow, and it will prompt for repositories or repository patterns to run the script against, unless the --octoherd-repos flag is set.

  2. The prompt to confirm a mutating request is much more helpful now.

     

     It now includes the name of the endpoint as you see it in GitHub's REST API Reference, it provides a link to the documentation, and most importantly, it allows you to permit all future mutating requests for the same route, or any route. I think that's a good compromise between being careful of not accidentally changing things, but also not overwhelming the user with prompts.

  3. Repository patterns can now have a * anywhere in the repository name. So instead of "octoherd/*", you can e.g. pass "octoherd/script-*"

  If you created an @octoherd script before the release of v3, you should have received a pull request like this one. If you didn't get a pull request, make sure to install the Octoherd App for future updates. We hope to help you that way to keep your scripts updated.

• There are several new scripts for you to use and learn from:

  • @octoherd/script-hello-world - the obligatory "Hello, world!" script
  • @octoherd/script-delete-repository - delete repositories
  • octoherd-script-normalize-package-repository-field - Remove redundant information from repository, homepage, bugs fields in package.json, by yours truly
  • octoherd-script-copy-labels - copies labels from one repo to the next, by @bdougie
  • octoherd-script-set-pr-merge-config - set pull request merge config, by @MunifTanjim
  • octoherd-script-replace-all-repository-topics - replace all repository topics, by @oscard0m
  • octoherd-script-watch-unwatch-or-ignore - watch, unwatch or ignore repositories, by @oscard0m

🔜 What's next

• I want scripts to define options that are specific to the script. This will allow the CLI and what ever runner the future brings a (better) way to verify options before the script is even run. I'm intrigued by superstruct and will experiment if it's good fit to define script options. I like the API and the fact that we that the option types can be inferred easily.
• Deno compatibility. @octoherd is a great fit for Deno with its secure sandboxing and explicit permissions. I'd like to make it possible to run the scripts with deno instead of node, and probably implement the octoherd CLI with deno

👋🏻 Contributions welcome

All issues with a pull request welcome label are ready for the taking! Contributions of all kinds are welcome 🖤:octocat: