DEV Community: Jordan Duabe

Programming a digital badge (with a Badger2040 and MicroPython)

Jordan Duabe — Fri, 16 Jun 2023 13:00:00 +0000

Badger2040 is a programmable E Paper/eInk/EPD badge, powered by the RP2040.

Some of its features:

2.9" black and white E Ink® display (296 x 128 pixels)
Powered by RP2040 (Dual Arm Cortex M0+ running at up to 133Mhz with 264kB of SRAM)
2MB of QSPI flash supporting XiP
Five front user buttons
Reset and boot buttons (the boot button can also be used as a user button)
USB-C connector for power and programming
JST-PH connector for attaching a battery (input range 2.7V - 6V)

I got one to play around with and to use as a digital lanyard / badge when attending meetups.

Programming

The Badger2040 ships with a custom MicroPython build and a graphics library PicoGraphics that contains useful utilities for drawing on the screen. There are also a couple of examples loaded on the device by default.

In order to write code or update / run the existing code samples, you’ll need to connect it to your computer and open up an IDE with MicroPython support i.e. Thonny.

One thing to note is you opt to use a different IDE is to make sure to name the file as main.py as it will be automatically run once uploaded to the device (this is the default behavior of the RP2040), otherwise your code will not be executed.

I ended up using PyCharm with the MicroPython plugin, one extra step I needed to do was to point the plugin to the device which was located at /dev/ttyACM0(if you’re on a Unix environment).

Drawing

With the following built-in functions, we can draw text and shapes on the screen.

Constants

The screen dimensions are provided as constants.

import badger2040
WIDTH = badger2040.WIDTH # 296
HEIGHT = badger2040.HEIGHT # 128

Pen

There are 16 pen colours - or “shades of grey” - to choose, from 0 (black) to 15 (white).

import badger2040
display = badger2040.Badger2040()
display.set_pen(
  colour # int: color from 0 to 15
)

The thickness of the lines drawn on the screen can be also be configured.

import badger2040
display = badger2040.Badger2040()
display.set_thickness(
  value # int: thickness in pixels
)

Text

The font can be changed with the set_font method and write using the text function.

import badger2040
display = badger2040.Badger2040()
# Available fonts
#
# Bitmap
# - bitmap6
# - bitmap8
# - bitmap14_outline
#
# Vector
# - sans
# - gothic
# - cursive
# - serif_italic
# - serif
display.set_font(font)
display.text(
  text, # the text string to draw 
  x, # the destination X coordinate
  y, # the destination Y coordinate
  wordwrap, # number of pixels width before trying to break text into multiple lines
  scale, # size
  angle, # rotation angle (Vector only!)
  spacing # letter spacing
)

Shapes

There are quite a few functions available here, I just included the ones I used. You can check out the full list in the Pico Graphics function reference.

Line

import badger2040
display = badger2040.Badger2040()
display.line(x1, y1, x2, y2)

Rectangle

import badger2040
display = badger2040.Badger2040()
display.rectangle(x, y, width, height)

Putting it all together

# Using the Badger2040 as a digital badge / lanyard

import badger2040

WIDTH = badger2040.WIDTH    # 296
HEIGHT = badger2040.HEIGHT  # 128

BANNER_HEIGHT = 30
BANNER_TEXT_SIZE = 0.8
NAME_PADDING_LEFT = 60

# badge contents
BANNER = "Random Event"
NAME = "First Name"
HANDLE = "@handle"

display = badger2040.Badger2040()

# draw banner
display.set_pen(15)
display.set_font("serif")
display.text(BANNER, 20, (BANNER_HEIGHT // 2) + 1, WIDTH, BANNER_TEXT_SIZE)
display.rectangle(1, BANNER_HEIGHT + 1, WIDTH + 1, HEIGHT - BANNER_HEIGHT)

# draw name
display.set_pen(0)
display.set_thickness(2)
display.set_font("sans")
display.text(NAME, NAME_PADDING_LEFT, HEIGHT - 60, WIDTH, 1.7)
display.text(HANDLE, NAME_PADDING_LEFT, HEIGHT - 20, WIDTH, 0.7)

# draw border enclosing banner and name
display.set_thickness(5)
display.line(WIDTH, 0, WIDTH - 1, HEIGHT)
display.line(0, HEIGHT, WIDTH - 1, HEIGHT - 1)

display.update()

The code is also available on GitHub as a gist.

Programmatically invoking JetBrains IDE actions

Jordan Duabe — Sat, 20 May 2023 05:22:32 +0000

Update (2024-03-08):

JetBrains has since released an official plugin on August 2023 but if you're running Linux (Stream Deck SDK only supports Windows and Mac currently) you may still find this article guide useful.

I’ve had a Stream Deck for a while now but haven’t really configured it for any coding related workflows. I use several JetBrains IDEs for work and personal use (IntelliJ, PyCharm, WebStorm to name a few), so I started looking into what the possible options were.

The simplest solution would be to just invoke keyboard shortcut for a specific but the downside of this approach is you can only have so much keycodes assigned (which may conflict with system shortcuts and possibly other apps), not to mention you’d have to change these when you switched keymaps or used another operating system.

Ideally there would be a command where you can provide an action to the IDE, possibly through a plugin.

IDE Scripting Console

While reading through the IntelliJ documentation, I stumbled upon the IDE scripting console.

The IDE Scripting Console can be used to write simple scripts that automate IntelliJ IDEA features and extract various information. With access to the IntelliJ platform API, you can think of it as a lightweight alternative to a plugin, which adds or modifies some behavior of the IDE.

By default, it supports scripts written in Kotlin, JavaScript, and Groovy. However, you can use any scripting language that is compliant with JSR 223, for example, Python, Ruby, Clojure, and so on.

This looks promising; I copied and modified some sample code from the docs to display a “Hello World” message in a dialog in the IDE.

import com.intellij.openapi.ui.Messages
val b = bindings as Map<String, Any>
val IDE = b["IDE"] as com.intellij.ide.script.IDE
Messages.showInfoMessage("Hello World")

Invoking Actions

The next step was figuring out how to invoke actions in the IDE. The IntelliJ Platform Plugin SDK defines the requirements in itsAction system documentation.

An ActionManager instance is used to execute an IDE Action that is referred to by its unique id – this can either be a custom action from an installed plugin or the standard IntelliJ Platform actions.

The following snippet executes the standard NextTab action:

import com.intellij.openapi.actionSystem.ActionManager
import com.intellij.openapi.actionSystem.AnAction
val b = bindings as Map<String, Any>
val IDE = b["IDE"] as com.intellij.ide.script.IDE
val actionManager: ActionManager = ActionManager.getInstance()
// move focus to the next editor tab
val action: AnAction = actionManager.getAction("NextTab")
actionManager.tryToExecute(action, null, null, null, false)

Invoking the script from the command line

Up to now, I’ve been able to play around with the scripts from within the IDEs – the next step is to find a way to invoke them externally.

Fortunately, this feature is already available since version 2021.1; it requires the command line scripts for the IDEs to be installed e.g.idea for IntelliJ IDEA. This can be configured via the JetBrains Toolbox.

The command to run script(s) is idea ideScript <files>.

Caveat: The script does not work (when invoked from the command line at least) unless the IDE action execution code is wrapped in the following snippet:

IDE.application.invokeLater {
// action execution code goes here
}

My guess is that it needs to be non-blocking, since it is invoked externally. One other thing to note is that if you have multiple windows of an IDE running, the action will be executed in the last active window.

Parameterizing the script

The last thing I wanted to add was to parameterize the script, where I could pass in the action name e.g. “Run tests” and the IDE where the aforementioned action would be executed.

I tried a couple of things; my first implementation involved passing the params as environment variables and parsing them in the script. That didn’t seem to work as when I tried to log the params they would always be null. The next thing I tried was to reading the params from a text file which also did not work.

Eventually, my solution involved creating a shell script that:

Requires (and parses) the IDE name and action name as arguments
Writes out the IDE script to a file (taking params into account)
Executes the IDE script
Deletes the IDE script file

So if I wanted to perform an action on an Intellij IDEA window, the command will look like ide-script.sh --ide idea --action action_name_to_perform

Putting it all together

As a side note, Intellij IDEA ships with Kotlin so the samples will work there – it may work on other IDEs if the Kotlin plugin is installed but I haven’t tested that so YMMV.

I ended up using Groovy since that ships with the other IDEs I mentioned earlier and I’ve been able to verify that it works on WebStorm and PyCharm. As for operating systems, I’ve tested this script on both macOS and Linux. The steps should be similar on Windows; you also might be able to reuse the shell script if you are running WSL but I imagine you’ll need to update the path of the command-line IDE launchers.

#!/usr/bin/env bash

set -Eeuo pipefail
trap cleanup SIGINT SIGTERM ERR EXIT

script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)
ide_script_name="ide_script.groovy"

usage() {
  cat <<EOF
Usage: $(basename "${BASH_SOURCE[0]}") [-h] [-f] -i ide -a action
Shell script wrapper that executes actions on JetBrains IDEs via the scripting console.
Available options:
-h, --help    Print this help and exit
-i, --ide     JetBrains IDE command-line launcher e.g. idea, webstorm, pycharm
-a, --action  IDE action to execute
EOF
  exit
}

cleanup() {
  trap - SIGINT SIGTERM ERR EXIT
  rm -f "$script_dir/$ide_script_name"
}

setup_colors() {
  if [[ -t 2 ]] && [[ -z "${NO_COLOR-}" ]] && [[ "${TERM-}" != "dumb" ]]; then
    NOFORMAT='\033[0m' RED='\033[0;31m' GREEN='\033[0;32m' ORANGE='\033[0;33m' BLUE='\033[0;34m' PURPLE='\033[0;35m' CYAN='\033[0;36m' YELLOW='\033[1;33m'
  else
    NOFORMAT='' RED='' GREEN='' ORANGE='' BLUE='' PURPLE='' CYAN='' YELLOW=''
  fi
}

msg() {
  echo >&2 -e "${1-}"
}

die() {
  local msg=$1
  local code=${2-1} # default exit status 1
  msg "$msg"
  exit "$code"
}

parse_params() {
  ide=''
  action=''

  while :; do
    case "${1-}" in
    -h | --help) usage ;;
    -v | --verbose) set -x ;;
    --no-color) NO_COLOR=1 ;;
    -f | --flag) flag=1 ;;
    -i | --ide)
        ide="${2-}"
        shift
        ;;
    -a | --action)
        action="${2-}"
        shift
        ;;
    -?*) die "Unknown option: $1" ;;
    *) break ;;
    esac
    shift
  done

  args=("$@")

  # check required params and arguments
  [[ -z "${ide-}" ]] && die "Missing required parameter: ide"
  [[ -z "${action-}" ]] && die "Missing required parameter: action"

  return 0
}

# Invoke supported IDE actions using the IDE scripting console. See links for more details.
# 
# Supported IDE actions: https://github.com/JetBrains/intellij-community/blob/idea/231.8109.175/platform/ide-core/src/com/intellij/openapi/actionSystem/IdeActions.java
# IDE scripting console: https://www.jetbrains.com/help/idea/ide-scripting-console.html
generate_ide_script() {
  cat <<EOF
import com.intellij.openapi.actionSystem.ActionManager
import com.intellij.openapi.actionSystem.AnAction
import com.intellij.openapi.ui.Messages
var actionManager = ActionManager.getInstance()
IDE.application.invokeLater {
  try {
    var action = actionManager.getAction("$action")
    var result = actionManager.tryToExecute(action, null, null, null, false)
    if (result.rejected) {
      Messages.showErrorDialog(result.error, "IDE action error")
    }
  } catch (ex) {
    Messages.showErrorDialog(ex.message, "IDE action error")
  }
}
EOF
}

parse_params "$@"
setup_colors

# Generate IDE script and execute the given action
ide_script="$script_dir/$ide_script_name"
generate_ide_script > "$ide_script"
$ide ideScript "$ide_script"
cleanup

The code is also available on GitHub as a gist.

Demo: Launching the Help Menu programmatically

The Help Menu action is invoked programmatically by clicking on a configured button on the Stream Deck.

View full size image here.

I hope others find this useful; now on to configuring the Stream Deck.

Contributing to open-source mechanical keyboard firmware

Jordan Duabe — Tue, 25 Apr 2023 09:16:02 +0000

Built the NCR-80 last year, great-looking board especially if you like the retro aesthetic, and is a pleasure to type on.

One thing I did notice was that the product listing points to a Google Drive link to the precompiled firmware, but it hasn’t been added to the QMK and VIA repositories. I thought this would be a good weekend project (Spoiler: it took longer than a weekend).

I wrote the steps of how I got it done (the steps also apply to any keyboard firmware).

Converting KBFirmware JSON to QMK

The starting point is to convert the KBFirmware JSON from the provided “QMK” files from the product listing, and then converting them to QMK formatted files.

There are a couple of tools that can be used for this purpose:

Recommended: KBFirmware JSON to QMK Parser
Deprecated: Keyboard Firmware Builder

The resulting files will be the base of the QMK firmware for the keyboard.

Creating a QMK pull request

Make sure to read the contribution guide as a first step. It is also a good idea to check out other supported keyboard firmware to get a feel for the directory structure, and conventions in use.

A keyboard firmware folder (simplified example) should look something like:

mt
|-- ncr80
| |-- keymaps
| |-- default
| |-- keymap.c
|-- info.json
|-- readme.md
`-- rules.mk

In cases where keyboards have multiple versions or revisions e.g. rev1, rev2 or hotswap/soldered, the directory structure will look different; refer to QMK’s contribution guide linked above.

Link to the pull request on GitHub for reference: [Keyboard] Add NCR-80

Creating a VIA pull request

In order to add VIA support for a keyboard, it is required to enable the VIA feature in QMK, and adding a via-compatible keymap for the keyboard. You can check out the QMK pull request linked above; look for the keymaps/via directory.

Read the VIA docs for configuring QMK for a more in-depth guide. I also recommend reading about the VIA spec.

It is also required to have the QMK pull request merged in before contributing to the VIA repository.

VIA V2 vs V3 definitions

It is basically just a matter of copying the VIA json files from the Drive link referenced at the start of this post. The main difference here is the location of the definitions depend on the version; V2 definitions are located in thesrc/<manufacturer>/<keyboard> directory while the V3 definitions are in the v3/<manufacturer>/<keyboard>.

If you have a V2 definition, you can convert it a V3 definition by running the scripts/build-all.ts file in thevia keyboards repository.

Link to the pull request on GitHub for reference: Add support for NCR-80

That’s it, once the pull request gets merged VIA should be able to detect your keyboard.

Writing a custom Powerline plugin

Jordan Duabe — Sun, 12 Sep 2021 12:20:20 +0000

Powerline is a tool I use as part of my dev environment setup, and have my config backed up as part of my dotfiles.

While it comes with a lot of integrations out of the box i.e. bash, zsh, tmux, vim, etc, it also provides a way for you to write your own "segments". This should serve as a quick guide for rolling your own custom Powerline plugin.

Basic structure and configuration

Each powerline segment is a callable object. It is supposed to be either a Python function or powerline.segments.Segment class.

I recently wrote my own custom one that displays the current Kubernetes context and namespace, which uses a Segment class. Here is a shortened version which shows the basic structure.

class KubernetesSegment(Segment):
    """Constructs the segment's sections with the configured colorscheme and
    visibility options applied."""

    @staticmethod
    def kube_ctx_info(pl):
        """Resolves the current active Kubernetes context (and namespace)
        from `$KUBECONFIG`."""
        try:
            current_context = config.list_kube_config_contexts()[1]
            return current_context['name'] or 'N/A', \
                   current_context['context']['namespace'] or 'default'
        except Exception as e:
            pl.error(e)

    def __call__(self, pl):
        pl.debug('Running powerline-k8s...')

        sections = []

        # additional logic to determine segment contents

        sections.append({
            'contents': f'u'\U00002638' ',
            'highlight_groups': 'k8s',
            'divider_highlight_group': 'k8s:divider',
        })

        return sections

k8s = with_docstring(KubernetesSegment(),
"""Return the current Kubernetes context and namespace.

It will show the current context and namespace from `$KUBECONFIG`.

Divider highlight group used: ``k8s:divider``.

Highlight groups used: ``k8s``, ``k8s_context``, ``k8s_namespace``.
""")
"""Custom segment entry point."""

Make sure to add the powerline-status package as a dependency.

Basically the class contains a function that returns a Segment dictionary which tells Powerline what to display. In this particular example, the following keys were used:

contents: Actual segment contents, excluding dividers and before/after. May be None.
highlight_groups, divider_highlight_group: Used highlight groups. May be None.

Highlight groups determine the 'style' that is used for a particular segment e.g. background and foreground, divider color to clearly distinguish one segment from another.

The colors that are available to you will depend on the current colorscheme that you are using. In general you'll need to add the "groups" definition to the colorscheme config file, which in this case was <powerline_dir>/colorschemes/solarized.json.

{
  "k8s":           { "fg": "solarized:blue", "bg": "solarized:base02", "attrs": [] },
  "k8s:divider":   { "fg": "gray4",          "bg": "solarized:base02", "attrs": [] }
}

Check out the Powerline docs for a more detailed view into
configuration and customization.

The next step is to let Powerline know of the new segment by adding it to the segment's config file. To add the new segment to the current shell prompt, add the following entry to the <powerline_dir>/themes/shell/default.json config file.

{
  "function": "k8s",
  "priority": 30
}

Installation

Once all configuration has been done it's time to "install" the segment and try it out, you can do so by executing:

$ python3 -m pip install --editable .

Installing the package in editable mode saves you from having to "re-install" to see the latest changes. If everything went well you should be able to see your new segment.

Troubleshooting

Having issues with your plugin, try out the following:

Run powerline-lint to check for errors in the configuration files i.e. colorscheme and/or segment config.
Restart powerline by running powerline-daemon --replace.
Configure logging with PowerlineLogger and where you want the logs to be written for easier debugging.

It is also worth checking out the Powerline docs for other common issues that you may encounter.

Misc

Check out the full source on GitHub for the powerline-k8s plugin.
If you want to share your custom Powerline segment, you might want to check out this guide about publishing packages to PyPI.

Publishing to Maven Central

Jordan Duabe — Sun, 25 Jul 2021 07:38:23 +0000

This guide walks you through the necessary steps to upload your package to the Maven Central repository (and optionally to GitHub Packages registry) with some recommendations along the way.

Setup OSSRH Repository

Sign up for a new account
Create a new project ticket
Claim your namespace by setting the groupId for your artifact

If you’re using a free code hosting service like GitHub or Bitbucket:

groupId: io.github.j4ckofalltrades

Alternatively if you want to use a custom domain, the group id should:

groupId: com.your-custom-domain

You will also need to prove ownership of the public repository or the custom domain. For the former you will be asked to create an empty repository using the ticket number for your created OSSRH ticket e.g. OSSRH-73148; for the latter you’ll need to add a TXT record linked to the OSSRH ticket that was created to register your groupId.

Configure GPG/PGP key

This will be used for signing your artifacts, at it is a requirement for publishing them to the Central Repository.

You’ll need to generate a key pair and distribute it to a known key server (so that others can validate it).

The following examples show how to do this with GPG; you can download or install it using your package manager if it is not already available in your machine.

To generate a key pair, run:

$ gpg --gen-key

Fill in the details you are prompted for e.g. name, email, time of validity, and passphrase for the generated key. This passphrase and your private key are all that is needed to sign artifacts with your signature.

Once the key pair is generated, you’ll need to distribute your public key to a known key server i.e. keyserver.ubuntu.com. In order to do so, run the following commands:

# list gpg keys
$ gpg --list-keys
# the line starting with **pub** shows your public key details

# copy the keyid and run the following command
$ gpg --keyserver keyserver.ubuntu.com --send-keys <your_key_here>

To check that your key was successfully uploaded, you can search for it at https://keyserver.ubuntu.com using your public key (and prepending ‘0x’ to it).

Other supported key servers are keys.openpgp.org, and pgp.mit.edu.

Configure build script

In order to publish your artifact to the Central Repository, it will need to meet the following requirements:

Project coordinates
Javadoc and sources jar
POM metadata (includes project name and description, url, SCM info, license)
Sign artifacts with GPG/PGP

The configuration will vary slightly depending on the build tool you are using, below is an abridged sample configuration build.gradle.kts file (Kotlin DSL) used with gradle:

// build.gradle.kts

// project coordinates
group = "io.github.j4ckofalltrades"
version = "1.0.0"

// generate KDoc and Javadoc using Dokka
tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        named("main") {
            outputDirectory.set(file("docs"))
            moduleName.set("steam-webapi")
            includes.from("Module.md")
            displayName.set("JVM")
            platform.set(org.jetbrains.dokka.Platform.jvm)
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(
                    URL(
                        "https://github.com/j4ckofalltrades/steam-webapi-kt" +
                            "/tree/main/lib/src/main/kotlin"
                    )
                )
                remoteLineSuffix.set("#L")
            }
        }
    }
}

// javadoc and sources jar
tasks {
    val sourcesJar by registering(Jar::class) {
        dependsOn(JavaPlugin.CLASSES_TASK_NAME)
        archiveClassifier.set("sources")
        archiveBaseName.set("steam-webapi-kt")
        from(sourceSets["main"].allSource)
    }

    val javadocJar by registering(Jar::class) {
        dependsOn("dokkaJavadoc")
        archiveClassifier.set("javadoc")
        archiveBaseName.set("steam-webapi-kt")
        from("docs")
    }

    artifacts {
        archives(sourcesJar)
        archives(javadocJar)
        archives(jar)
    }
}

publishing {
    publications {
        create<MavenPublication>("mavenJava") {
            groupId = project.group.toString()
            artifactId = rootProject.name
            version = project.version.toString()

            from(components["java"])
            artifact(tasks["sourcesJar"])
            artifact(tasks["javadocJar"])

            // POM metadata
            pom {
                name.set("steam-webapi-kt")
                description.set("Steam WebAPI wrapper in Kotlin and Ktor")
                url.set("https://github.com/j4ckofalltrades/steam-webapi-kt")
                licenses {
                    license {
                        name.set("MIT")
                        url.set("https://opensource.org/licenses/MIT")
                    }
                }
                developers {
                    developer {
                        id.set("j4ckofalltrades")
                        name.set("Jordan Duabe")
                        email.set("me@jduabe.dev")
                    }
                }
                scm {
                    connection.set("scm:git:git://github.com/j4ckofalltrades/steam-webapi-kt.git")
                    developerConnection.set("scm:git:ssh://github.com/j4ckofalltrades/steam-webapi-kt.git")
                    url.set("https://github.com/j4ckofalltrades/steam-webapi-kt")
                }
            }
        }
    }
    repositories {
        // Maven Central
        maven {
            name = "OSSRH"
            url = uri("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
            credentials {
                username = System.getenv("OSSRH_USERNAME")
                password = System.getenv("OSSRH_PASSWORD")
            }
        }
        // GitHub Packages
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/j4ckofalltrades/steam-webapi-kt")
            credentials {
                username = System.getenv("GITHUB_ACTOR")
                password = System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

// sign artifact
signing {
    setRequired({
       gradle.taskGraph.hasTask("publishMavenJavaToOSSRHRepository")
    })

    val signingKey = System.getenv("SIGNING_KEY")
    val signingPassword = System.getenv("SIGNING_PASSWORD")
    useInMemoryPgpKeys(signingKey, signingPassword)
    sign(publishing.publications["mavenJava"])
}

Publishing artifacts

The configuration above uses the in-memory ascii-armored keys approach for signing artifacts. Check out the docs for the Gradle Signing Plugin to find out what best suits your use case.

Once everything is configured, publishing the artifacts is as simple as running:

$ gradle publish

Note that this will publish your artifacts to all target repositories, in order to publish to a specific repository you need to specify the repo name. Using the above configuration as an example:

# publish to Maven Central
$ gradle publishMavenJavaPublicationToOSSRHRepository

# publish to GitHub Packages
$ gradle publishMavenJavaPublicationToGitHubPackagesToRepository

Releasing artifacts

Login to the Nexus staging repository, where you should be able to see your groupId listed. In order to sync the artifacts to the Central Repository you’ll need to click on the Close button which will close said staging repository.

The close operation will run a series of checks to ensure that the uploaded artifacts meet the requirements.

If the release was successful, you should be able to see your artifacts in the Central Repository at https://repo1.maven.org/maven2/, typically within ~30 minutes. Updates to https://search.maven.org can take up to a couple of hours.

Bonus: Automation with GitHub Actions

You’ll probably want to automate this process as part of your CI/CD pipeline. Here’s how to set it up using GitHub Actions.

You’ll need to add your OSSRH credentials, and signing key details as secrets to your repository, you can find this under Settings > Secrets.

name: Publish to OSSRH and GitHub Package Registry

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'adopt-openj9'
          java-version: '17'
      - run: ./gradlew publish
        env:
          GITHUB_ACTOR: ${{ github.actor }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
          SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
          SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}

The configuration samples used here can also be checked out in full at this GitHub repository.

That’s it, time to get publishing.

Publishing to the npm registry

Jordan Duabe — Sat, 19 Jun 2021 05:43:02 +0000

This guide walks you through the necessary steps to upload your package to the npm registry with some recommendations along the way.

Setup npm account

Register for an npm account
Test your account by logging in using npm

# you should be prompted for your username, password, and email address
# and an OTP if you've enabled 2FA
$ npm login
# this should print out your npm username
$ npm whoami

Dry-run (Testing your package locally)

Test out your package locally to ensure that everything works before publihsing it to the npm registry. You can do this by invoking npm install and providing the path to your package e.g.:

$ npm install /path/to/your/package

Another thing to do is to review the contents of the published package to make sure that it doesn’t include any sensitive or unnecessary information. You can perform a dry-run with:

$ npm publish --dry-run
# output should look something like
npm notice
npm notice <package_name@version>
npm notice === Tarball Contents ===
npm notice <tarball_contents_here>
npm notice === Tarball Details ===
npm notice <tarball_details_here>
npm notice
+ <package_name@version>

Additionally you can create a .npmignore file to exclude files that you don’t want to publish to the registry.

Publishing to the npm registry

In your package’s root directory, execute:

$ npm publish

If publishing a scoped public package, execute:

$ npm publish --access public

When the publish process finishes, you should be able to see your public package page at https://npmjs.com/package/your-package-name.

Congrats, you’ve successfully published your package to the npm registry. 🎉

Bonus: Automation with GitHub Actions

You’ll probably want to automate this process as part of your CI/CD pipeline. Here’s how to set it up using GitHub Actions.

Create a new npm access token
Add the access token as a secret to your target GitHub repository. You can find this under Settings > Secrets for your repo. Give the secret a name e.g.NPM_TOKEN.
Create a GitHub action workflow file in your repo at.github/workflows/npm-publish.yml with the following contents:

name: Publish package to npm

on:
release:
    types: [created]

jobs:
build:
    runs-on: ubuntu-latest
    permissions:
    contents: read
    packages: write
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
        with:
        node-version: '18.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm install
    - run: npm test
    - run: npm run build
    # Publish to npm (append `--access public` for scoped packages)
    - run: npm publish
        env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

This workflow is triggered when a new release is created but you can also configure it to be triggered when a different event happens e.g. when a new tag gets pushed. Refer to the GitHub Actions documentation for more configuration options.

That’s it, time to get publishing.

Publishing to PyPI

Jordan Duabe — Sun, 13 Jun 2021 14:08:53 +0000

This guide walks you through the necessary steps to upload your package to the 🐍 Python Package Index (PyPI) with some recommendations along the way.

Dry-run (Publishing to TestPyPI)

This step is optional but recommended.

TestPyPI is a separate instance of the real package index which is intended for testing and experimentation. This is a good way to test out your package before uploading to the real index.

Register an account for TestPyPI
Create a TestPyPI API token – make sure to set the scope to “Entire account”
Use twine to upload your package

$ python3 -m pip install --upgrade twine
# replace dist with the directory where your distribution archive is located
$ python3 -m twine upload --repository testpypi dist/*

You will be prompted for your TestPyPI username and password. Use the following values.

username	password
`__token__`	API token including the `pypi-` prefix

Alternatively you can also use a .pypirc file to define your package indexes config i.e. TestPyPI, PyPi. If you choose to go this route, create a $HOME/.pypirc file with the following contents:

[testpypi]
username=__token__

You can also use the password field and paste in your API token but the recommended way is to use keyring (which is installed by Twine) for saving credentials such as API tokens and passwords. You can do so with:

$ keyring set https://test.pypi.org/legacy/ <value_of_api_token>

Once the upload process has finished, you should be able to view your package on TestPyPI at https://test.pypi.org/project/your-package-name.

Installing and testing out your package

$ python3 -m pip install \
--index-url https://test.pypi.org/simple/ --no-deps your-package

Note that the no-deps flag is specified as one or more of your package’s dependencies might not be present in TestPyPI and may cause the installation to fail.

Once the installation has finished you can test it out by importing your package.

$ python3
>>> from example_package import your_function
>>> your_function.do_something()

Note that the import package will always be example_package regardless of the name you’ve configured for your package.

That’s it, you can now try and upload your package to the real index.

Publishing to PyPI

The steps are identical with how you would upload a package to TestPyPI. The main difference is that you’ll have to register an account and create an API token at PyPI, as the former is a separate instance of PyPI.

Register an account for PyPI
Create a PyPI API token – make sure to set the scope to “Entire account”
Use twine to upload your package

$ python3 -m pip install --upgrade twine
# replace dist with the directory where your distribution archive is located
$ python3 -m twine upload --repository pypi dist/*

You will be prompted for your PyPI username and password. Use the following values.

username	password
`__token__`	API token including the `pypi-` prefix

Alternatively you can also use a .pypirc file to define your package indexes config i.e. TestPyPI, PyPi. If you choose to go this route, create a $HOME/.pypirc file with the following contents:

[pypi]
username=__token__

$ keyring set https://upload.pypi.org/legacy/ <value_of_api_token>

When the upload process finishes, you should be able to view your package on PyPI at https://pypi.org/project/your-package-name

Installing and testing out your package

$ python3 -m pip install your-package

Once the installation has finished you can test it out by importing your package.

$ python3
>>> from example_package import your_function
>>> your_function.do_something()

Congrats, you’ve successfully published your package to PyPI. 🎉

Bonus: Automation with GitHub Actions

You’ll probably want to automate this process as part of your CI/CD pipeline. Here’s how to set it up using GitHub Actions.

Create a new PyPI API token
Add the API token as a secret to your target GitHub repository. You can find this under Settings > Secrets for your repo. Give the secret a name e.g.PYPI_API_TOKEN.
Create a GitHub action workflow file in your repo at.github/workflows/pypi-publish.yml with the following contents:

name: Publish package to PyPI

on:
release:
    types: [created]

jobs:
build-n-publish:
    name: Build and publish to PyPI
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master

    - name: Set up Python 3.9
      uses: actions/setup-python@v4
      with:
        python-version: 3.9

    - name: Install pypa/build
        run: >-
        python -m
        pip install
        build
        --user

    - name: Build a binary wheel and a source tarball
        run: >-
        python -m
        build
        --sdist
        --wheel
        --outdir dist/
        .

    - name: Publish package
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

That’s it, time to get publishing.

Hacktoberfest 2020 Retrospective

Jordan Duabe — Sat, 23 Jan 2021 04:50:21 +0000

This one’s long overdue and when the swag arrived last week I figured I really need to get this done.

The past year has been tough to say the least and getting to write code for fun while helping out the open-source community was a very welcome distraction.

Though I have been programming for a while this was my first time participating in Hacktoberfest and contributing to open-source in general, it was nice to get to talk to and interact with maintainers and other like-minded individuals who are passionate about code and giving back to the community.

Even with all the drama that surrounded this past year’s iteration I’d say this was a positive experience overall, and I look forward to joining this year’s iteration.

Here are some of the projects I found interesting and contributed to (and still try to contribute to):

Happy hacking!