michaelheap.com

How I work: Email

2023-09-09T11:06:19Z

Depending on who you ask, I’m excellent with email, or terrible with email. I don’t let it run my life, and process my (work) inbox every 2-3 days.

My review process has four steps: triage, unsubscribe, respond and prioritise.

Triage: Read all unread emails in my inbox with the search is:unread in:inbox.
If there are emails that I don’t want to receive (e.g. cold outreach) I create a filter based on the sender so that it doesn’t land in my inbox
Things that take 2 minutes to answer are responded to immediately. Otherwise they’re labelled (not starred - more on this later) for action later
Finally, I go through my labelled items and import them in to Sunsama to be scheduled alongside my other work.

The Klinger email method

I’ve been using a multiple inbox setup from Andreas Klinger for years. Having a main inbox, then separate inboxes for high/medium priority emails allowed me to keep on top of things that I needed to do.

Go and read the Klinger email method now

However, since I started using Sunsama my inbox is no longer the source of truth for what I need to do. Instead, it’s an input in to my Sunsama plan.

Pain Points

The Klinger method is great, but it isn’t perfect. I have two big complaints, and they both have to do with the use of custom stars.

The mobile gmail app only supports star/unstar, not custom stars
Sunsama only support starred/unstarred, which meant I lost my high/medium priority differentiation

To work around this issue, I created two labels: priority/high and priority/medium. I use these for my custom inboxes instead of the red and yellow bang stars from the Klinger method. This allows me to set priorities on mobile, and filter to specific priorities within Sunsama.

The real game changer for me was when I learned that you can customise label colours. Click on the three dots next to the label name in the sidebar and choose a label colour. I chose red for high priority and yellow for medium priority. The colours help these emails stand out when I’m scrolling through my inbox.

Sunsama Integration

Finally, it’s time to look at my Sunsama workflow for emails. I review emails tagged with priority/high or priority/medium on a Monday, Wednesday and Friday.

I start with priority/high and schedule work on those emails until the list is empty. Once there are no more remaining, I start working through priority/medium emails. When the email is imported in to Sunsama, the priority label is removed automatically which makes Sunsama the source of truth.

Email is one of my lowest priority task sources. I’ll always pull from Slack and GitHub before working through my email task backlog. However, everything that comes in via email does eventually need doing so pulling them in to Sunsama is important.

How I work: Sunsama

2023-09-08T16:41:16Z

I’m a big believer in Parkinson’s Law, which states that work will expand to fill its allotted time span. The work keeps coming, and no matter how well I prioritise my todo list it always seemed to be longer at the end of the day than it was at the beginning.

Thankfully in the last couple of years I’ve solved this issue using Sunsama, a tool for tracking and scheduling work across multiple systems.

Before I get started, I want to make one thing clear. This isn’t a paid post, and I don’t get anything for recommending Sunsama. I’m just a very happy user.

What is Sunsama?

Sunsama is a combined inbox for all of your different to-do systems. It sounds strange to have an inbox for your inboxes, but when work can appear in multiple different places it’s hard to keep track of. I know some people that try to make their email inbox their to-do list, but it never worked for me.

Depending on which role I’m fulfilling, my work comes from different places. If I’m being an engineer, I’m pulling from Jira (or GitHub, depending on which team I’m working with). As a manager I’m usually responding to questions in Slack or by email. If I’m collaborating with the marketing team the tasks come via Asana, and if it’s something I’ve captured myself whilst away from my desk it’s in my work project in Todoist.

Trying to keep track of everything I need to do across all of those systems is impossible. There’s no way to rank the tasks against each other and build a consolidated, prioritised list. That’s where Sunsama comes in. It allows me to pull in tasks from all of those systems and see them in a single screen.

More than that, Sunsama lets me estimate how long each will take and schedule the tasks around my meetings for the day. It’s sad to see that some days I only get around 2 hours of time to work on assigned tasks, but it’s better to know that’s the case than to plan 6 hours of tasks and be disheartened when most of them are still on my to-do list at the end of the day.

So that’s what Sunsama is for me: a consolidated inbox that allows me to schedule tasks on my calendar to keep me honest when it comes to capping my work day at 8 hours.

Integrations

Sunsama’s killer feature is its deep integration with other products. Once upon a time I spent most of my time pulling in Jira and GitHub tasks, but now it tends to be more Slack messages and emails. Here’s my integration tier list:

S Tier: Slack (easily 75%+ of my tasks), Email
A Tier: Email, Jira, Todoist
B Tier: GitHub
C Tier: Asana

Sunsama also integrates with Trello, Notion, Outlook, ClickUp and Linear but I don’t use those tools and can’t talk about how well they work.

One of the things I love about Sunsama is that you can interact with the underlying service directly in the UI. Here’s an example of how Sunsama renders a Jira ticket. It feels familiar, and allows me to see the ticket details and update the status without leaving Sunsama.

My Sunsama Workflow

Calendar Setup

Sunsama works best when you schedule your work on your calendar. I prefer to keep my planned work separate from my meetings, so I created a second calendar to use with Sunsama. This gives me the ability to see everything in the Sunsama app, but only see my committed meetings in Google Calendar.

Channels

When I first started using Sunsama I didn’t use channels. It felt like I’d spend more time categorising work than actually doing it. However, as I started to try and build blocks of focused time I found that some coarse grained categorisation was helpful.

I don’t overdo it with channels, aiming to have as few as possible. Here’s what my current list looks like:

admin
aip
apiops
devrel
docs
kic
product
review
watch

Most of the channels are teams that I actively work with (aip, apiops, devrel, docs, kic), which leaves a couple of general areas. Anything that isn’t directly attached to a team is either admin, or something I need to review or watch. I recently split out watch as I realised that video is a much bigger time commitment than reviewing a doc.

Having each item categorised by channel allows me to batch up my day and focus on specific areas for an extended period of time. Which brings us on to the daily plan.

Daily Planning

Each morning starts with a review of what needs to get done today. I’m a heavy user of “save for later” in Slack, so the first thing that I do is go through my saved items and send them to Sunsama using the Slack integration. This works really well as Sunsama attaches a link to the conversation to the item so that I can navigate back to see additional context if needed. Any items created at this point go in to the “Today” list, or in to the backlog.

Once that’s done, I run through the “Today” list and ensure that all items have a channel set. This helps a little later on when I’m scheduling my day. If it looks like I’ll have some spare capacity during the day, I’ll try to move something from the future to today and get it done earlier (but not from the backlog. That happens once per week, which I’ll explain next).

Next, I group the items by channel before pressing the “Plan” button. I try to batch up my work by area to reduce context switching, which means that I get most of my work done in the mornings and have calls in the afternoon. I add all my events to my list of tasks so that I can see how many hours I have scheduled. Today is a busy day, and I have 7h15m of work planned to complete

At this point my day is planned and I can get started. I hover over the first item in the list, press F to enter focus mode then get started.

Backlog Review

Tasks that I can’t pick up in the next day or two get sent to the Sunsama backlog. Tasks in the backlog all have a channel set to help with the review process. Initially I tried to review the backlog on a Monday morning, but I found that most of the backlog tasks weren’t getting completed during the week.

Today, I process my backlog on a Thursday when I know how well my week is going and how much time I’ll have free on Thursday/Friday. I usually only manage to get one or two tasks out of the backlog, but manage to add around 5 per week. I’m not sure how to resolve this yet, but I follow a first-in, first-out model to try and get everything processed in a reasonable time.

When I take tasks from the backlog I try to choose tasks from a specific channel. This allows me to batch process and prevents context switching as I try to wrap things up before the end of the week.

Automation

Sunsama’s killer feature is the number of integrations there are, but that’s just the start. What really makes it powerful are the automations that you can configure for each platform.

Automations change the state of your task on the remote site based on actions within Sunsama. Here are a couple of ways that I use it:

When a Jira task is completed, prompt me to update the Jira ticket status
When a Gmail task is completed, unstar and archive the email in my inbox
When a Todoist task is completed, mark it as done in Todoist

This allows me to work entirely in Sunsama whilst still keeping external systems up to date.

Focus mode

Finally, we come to focus mode. I mentioned that I press F and get started with the day above, but let’s take a deeper look at focus mode. There are two ways to enter focus mode - the “Focus” button at the top of the current day, and pressing F whilst focused on a task.

Clicking “Focus” at the top will hide all other days and the left hand sidebar in the UI. It leaves you with your list of tasks for the day and whatever integration you have open on the right (for me this is always the calendar). This is handy to see an “at a glance” view of your day but I don’t use it much.

The alternative is to press F, which hides all sidebars and tasks except the one you were focused on. It shows the task title and metadata and brings up a small task timer (which I don’t use). I like to use this view to keep me focused on a single task, and it moves on to the next one in the list when I mark it as complete.

Features I don’t use

I feel like I’ve got a pretty good Sunsama workflow, but there are features that I don’t use too. Some of the features have been added recently and I just haven’t tried them out yet, whilst others don’t seem to fit my workflow.

Weekly objectives: Sunsama allows you to set key objectives for the week and associate your tasks with objectives. This keeps you focused on the strategic work. Unfortunately a lot of my work is escalation driven, so weekly objectives don’t work for me
Auto-archive: If a task keeps rolling over from day to day, Sunsama can remove it from your to-do list and move it to an archived section. I aggressively prune my task list manually so I have no use for auto-archive.
Time tracking: In addition to estimating how much time a task will take, Sunsama allows you track how much time you spend on each task. I just forget to do this.
Automatic scheduling: Sunsama can take the tasks for a day and automatically schedule them around your meetings. If you complete a task sooner than expected, it can re-plan your day automatically. I’ve disabled this feature, as I like to be in control of my own calendar. If I finish a task early, I prefer to stand up and walk around for a while
Daily shutdown: The end of day counterpart to the daily planning process. I do a lightweight version of this where I move incomplete items to the next day, but don’t review what was shipped. I do weekly reviews using a separate process outside of Sunsama with my wider team.

At some point I’d like to be more intention with my focus and try setting weekly objectives and try out time tracking to see if I’m spending time in the right areas.

Sunsama changed my (work) life

As someone that used to try and get everything on their to-do list done in a single day (and was inevitably disappointed when I didn’t make it all the way through), Sunsama has changed my life.

I’m fortunate that all the systems I interact with day to day are supported. In a previous role they migrated from Jira Cloud to Jira Server and Sunsama became much less useful for me.

If you’re working across multiple different systems and struggling to keep track of what needs to be done, why not give Sunsama a go?

GitHub Actions notifications in Slack

2023-09-05T09:04:52Z

I recently learned that GitHub can send you reminders on Slack at a regularly scheduled interval. What I didn’t know is that GitHub can also send you notifications on Slack in real-time when events that you’re interested in occur. In my case, that’s when a GitHub Actions build fails.

Ever since GitHub Actions launched, people have been reaching for prebuilt actions (usually Slack Notify) to send updates to Slack. It works great, but there are a couple of downsides to this approach:

You need your Slack admin to generate a webhook URL for you
Notification logic leaks in to your GitHub Actions builds
You can only notify a single channel at a time

In December 2022, GitHub launched support for GitHub Actions workflow notifications in Slack and Microsoft Teams, which allows you to configure Slack as a webhook receiver for GitHub Actions workflow notifications.

Notifications are configured on a per-channel basis using the /github subscribe command in Slack. To get started:

Invite @github to the channel you’d like to receive notifications in
Run /github subscribe owner/repo

Real World Usage

Here’s a real world example that we use to be notified about our scheduled broken links checker, which runs once per week:

bash
/github subscribe Kong/docs.konghq.com workflows:{name:"Scheduled Broken Links Checker"}

bash
✅ Subscribed to Kong/docs.konghq.com. This channel will receive notifications for
issues, pulls, commits, releases, deployments, workflows:{name:"Scheduled Broken Links Checker"}

That’s all! As you can see, you’ll get notifications for issues, pulls, commits (only on the default branch), releases and deployments by default. That’s a bit too much for me, and I unsubscribe from all of these notifications using the following:

bash
/github unsubscribe Kong/docs.konghq.com issues pulls commits releases deployments

Now the channel will only receive notifications for the named workflow:

bash
This channel will receive notifications from Kong/docs.konghq.com for:
workflows:{name:"Scheduled Broken Links Checker"}

You can filter the notifications by workflow name, the event on which the workflow is triggered, the person that triggered the workflow (useful to review your CEO’s pull requests quickly! 😉), or the branch on which the workflow is running. For a full set of documentation, see the GitHub workflow notification filters docs.

I feed these notifications in to a personal, private channel so that they don’t impact the rest of the team. I couldn’t do that as easily if we were using notify-slack directly in the pipeline.

Pull Request Notifications

Our main use case for the GitHub notifications in Slack is for workflow success/failure, but there is one other trick we use that I’d like to share.

We use labels heavily to categorise pull requests and control CI checks (including making labels required). Here are a couple of filters I use to make sure that I don’t miss anything:

/github subscribe Kong/docs.konghq.com +label:"review:tech" - Makes sure that I see any docs platform code changes
/github subscribe Kong/docs.konghq.com +label:"review:sme" - These are usually really interesting docs to read and learn from. If a topic needs SME (subject matter expert) review, there’s something for me to learn.
/github subscribe Kong/docs.konghq.com +label:"ci:manual-approve:linting" - Alert whenever the linting CI check is skipped. We have multiple manual-approve labels and I subscribe to all of them. You can see how we override workflows manually using labels in the linting workflow.

Give it a go

The GitHub Slack integration is pretty great. Whether you’re looking for GitHub Actions notifications, to be alerted when pull requests have a specific label or just to be reminded about PRs that need your review, I recommend trying them out to see what works for you.

Accessing secrets from forks safely with GitHub Actions

2023-09-04T14:05:28Z

It feels like I see someone asking “how do I let pull requests from forks access my GitHub Actions secrets?” every other day. GitHub prevents PRs from forks from accessing secrets by default so that they can’t exfiltrate secrets and use them for malicious purposes.

There are posts out there that show you how to use pull_request_target with actions/checkout to check out the HEAD ref, but this is insecure by default as it exposes all of your secrets to anyone that can raise a pull request against a repo (which is everyone on a public repo).

So, how do you get the best of both worlds? How can you safely provide secrets to forks without malicious actors stealing them?

GitHub Actions provides a triggering actor field that lets you know who ran (or re-ran) a workflow. This allows maintainers to provide access to secrets on forks once they’ve checked the changes manually and are happy that they don’t pose a security risk by re-running a job.

If you’re working in a private repo and want to enable secrets for forks, you can make them available via repo settings. This post is only relevant for public repos.

Here’s what the workflow would look like:

Alice opens a pull request from her fork
GitHub Actions runs and fails the build as she doesn’t have permissions on the repo
Bob reviews the PR and decides that there’s nothing dangerous
Bob re-runs the failed job
GitHub Actions runs and the access check passes as Bob has write access to the repo
github.event.pull_request.head.sha is checked out and points to Alice’s changes
The rest of the workflow runs successfully with access to any repository secrets

So in short:

Check permissions
Checkout code
Run tests with secrets

Check Collaborator Permissions

GitHub not trusting pull requests from forks is a proxy for “do we trust this person?”. Rather than asking the question “is the PR from a fork”, why don’t we check what permission the actor triggering the job has?

There are two ways to check permissions - author association or user permissions. Author association tells us if they have any permissions on the repository (they’ll be marked as a collaborator no matter what permissions they have). User permissions tells us exactly what permissions they have on the repository.

If you want to learn more about author associations vs user permissions see Check permissions in a GitHub Actions workflow

If you’re not sure which to choose, I recommend checking the actor’s permissions rather than relying on author association.

Author Association

The author association is available by default in the pull request event. This means that you can check permissions directly in a workflow without using the GitHub API:

yaml
- name: Check access
  if: ${{ github.event.pull_request.author_association != 'COLLABORATOR' && github.event.pull_request.author_association != 'OWNER' }}
  run: |
    echo "Event not triggered by a collaborator."
    exit 1

This step would check if the author of the PR has any access to the repo. If they do not, the workflow will exit with error code 1.

User Permission

Alternatively, you can check if the actor has specific permissions using a GitHub Action. I personally use the following action:

yaml
- name: Get User Permission
  id: checkAccess
  uses: actions-cool/check-user-permission@v2
  with:
    require: write
    username: ${{ github.triggering_actor }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Check User Permission
  if: steps.checkAccess.outputs.require-result == 'false'
  run: |
    echo "${{ github.triggering_actor }} does not have permissions on this repo."
    echo "Current permission level is ${{ steps.checkAccess.outputs.user-permission }}"
    echo "Job originally triggered by ${{ github.actor }}"
    exit 1

The action returns outputs that you can then use to determine what to do next. I check the permission in the second step above and print a debugging message before exiting with an error code of 1 to fail the build.

You might notice that I use github.triggering_actor rather than github.actor. This is what allows us to run tests from forks if the job is re-run by someone with the correct permission level.

When checking for permissions, the available levels are none, read, write and admin. Although triage and maintain are permissions in GitHub itself, they are not reflected in the API.

Check out the new code

At this point it’s safe to check out the code as the job has been triggered by someone with write access.

I mentioned earlier that using actions/checkout with github.event.pull_request.head.sha is insecure. However, as the PR has been reviewed and the workflow run has been triggered by someone with write access we can be a little more trusting.

Here’s how to check out the code from the PR in your workflow by explicitly setting a ref:

yaml
- name: Checkout code
  uses: actions/checkout@v3
  with:
    ref: ${{ github.event.pull_request.head.sha }} # This is dangerous without the first access check

Run the tests

Your workflow will be different to mine at this point. If you’re testing if you’ve configured things correctly, you can set a secret named MY_SECRET to val and use the following step:

yaml
- name: Test
  run: |
    if [[ "x${{ secrets.MY_SECRET }}" == "xval" ]]; then
      echo "Access to secrets"
    else
      echo "No access to secrets"
      exit 1
    fi

Putting it all together

Taking all of the above and combining it in to a single workflow gives us the following:

yaml
name: Run tests from fork
on:
  pull_request_target:
    types: [opened, synchronize]
jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - name: Get User Permission
        id: checkAccess
        uses: actions-cool/check-user-permission@v2
        with:
          require: write
          username: ${{ github.triggering_actor }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Check User Permission
        if: steps.checkAccess.outputs.require-result == 'false'
        run: |
          echo "${{ github.triggering_actor }} does not have permissions on this repo."
          echo "Current permission level is ${{ steps.checkAccess.outputs.user-permission }}"
          echo "Job originally triggered by ${{ github.actor }}"
          exit 1
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          ref: ${{  github.event.pull_request.head.sha }} # This is dangerous without the first access check
      - name: Run tests
        run: |
          if [[ "x${{ secrets.MY_SECRET }}" == "xval" ]]; then
            echo "Access to secrets"
          else
            echo "No access to secrets"
            exit 1
          fi

So there we have it - a mostly safe way to run workflows with access to secrets when a pull request is raised from a fork.

Why mostly safe rather than 100% safe? It relies on humans to read the pull request diff and make a good decision. We’re all human and mistakes happen. At some point a PR will get run that shouldn’t have been, and you’ll need to rotate your secrets.

I think it’s worth it. Being able to run your full suite of tests with secrets on PRs from forks is key to delivering robust software. If secrets get leaked by mistake, well, it’s always good to test your rotation procedure periodically 😁.

Setting `created_at` with GitHub Actions when a PR is merged

2023-08-21T07:37:42Z

The blog that you’re reading is a static site that’s generated on every push to main. That means that whatever’s in the repo is the source of truth, including the created_at date when a PR is merged.

I do a lot of my writing in batches, but don’t want to publish everything at the same time. Rather than keeping finished posts in Ulysses (my writing app of choice) and staging a new post every time I want to publish, I raise a pull request immediately and use GitHub Actions to set the created_at date when publishing a post.

Here’s the rough workflow:

Check if the submit-post label has been added
Fetch the list of changed files in the PR
For each added file, fetch the file contents
Replace the created_at date (it’s called date in the frontmatter) in each file (using .replace() but I should probably use gray-matter)
Use github.repos.createOrUpdateFileContents to update the contents of each file
Use github.pulls.merge with merge_method: "squash" to merge the PR as a single commit (createOrUpdateFileContents adds multiple commits)
Delete the branch

I could write a new GitHub Action to do this, but as it’s not reusable and it’s only a small number of lines I’ve chosen to use actions/github-script which lets me write JavaScript and use the GitHub API easily.

js
on:
  pull_request:
    types:
      - labeled
jobs:
  merge-label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v4
        id: set-result
        with:
          github-token: $
          script: |
            const labelName = context.payload.label.name;
            if (labelName != "submit-post"){
              console.log(`${labelName} label was added. No action needed`);
              return;
            }
            const {data: files} = await github.pulls.listFiles({
              pull_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
            });
            // Load all new files + their contents
            const newPosts = await Promise.all(files.filter(f => {
              return f.status == 'added' && f.filename.endsWith(".md")
            }).map(async f => {
              const blob = await github.request(`GET ${f.contents_url}`);
              const content = Buffer.from(blob.data.content, 'base64').toString();
              return {sha: f.sha, filename: f.filename, content};
            }));
            // Replace the date + updated_at with the current date
            const now = (new Date).toISOString();
            await Promise.all(newPosts.map(async f => {
              f.content = f.content.replace(/date: "[^"]+"/mi, `date: "${now}"`);
              f.content = f.content.replace(/updated_at: "[^"]+"/mi, `updated_at: "${now}"`);
              return await github.repos.createOrUpdateFileContents({
                owner: context.repo.owner,
                repo: context.repo.repo,
                path: f.filename,
                message: "Update date",
                branch: context.payload.pull_request.head.ref,
                sha: f.sha,
                content: Buffer.from(f.content).toString('base64'),
                committer: {
                  name: "Michael Heap",
                  email: "michael@example.com"
                }
              });
            }));
            // Wait 10 seconds for changes to propogate
            await new Promise((resolve) => {
              setTimeout(resolve, 10000);
            });
            // Squash and merge the PR
            await github.pulls.merge({
              pull_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              merge_method: "squash"
            });
            // Delete the branch
            github.git.deleteRef({
              repo: context.repo.repo,
              owner: context.repo.owner,
              ref: `heads/${context.payload.pull_request.head.ref}`
            });
          result-encoding: string

This action allows me to stage posts when I finish writing them rather than when I plan to publish. Once my intended publishing date arrives, I add the submit-post label to the PR (usually via my phone) and the post is published as intended.

kubectl autocomplete with ZSH and aliases

2023-08-19T12:12:20Z

This took me way too long to figure out.

How to make the k alias for kubectl autocomplete in zsh:

Ensure that setopt COMPLETE_ALIASES is not set (I’m not sure why) TODO: CHECK THIS
Define your alias alias k=kubectl
Load the kubectl completions withsource <(kubectl completion zsh)
Run compdef k='kubectl' to associate the autocomplete for kubectl with k

Here’s a complete .zshrc that works for me:

bash
autoload -Uz compinit
compinit
alias k=kubectl
source <(kubectl completion zsh)
compdef k='kubectl'

PS: Make sure that the aliases are set before calling compdef. That’s an hour of my time I’m never getting back.

Spider-shaped DevRel

2023-08-19T12:03:12Z

The “T-shaped people” theory states that people generally have a wide understanding of an area, or a deep one. It’s very rare that you find someone that is both wide and deep at the same time.

Deep:

Wide:

When it comes to Developer Relations, I’ve found that most companies expect us to be spider-shaped. Slightly less wide than a lot of professions, and slightly deeper than most others:

Examples

Working in DevRel, you need to fulfil multiple roles. You might build a demo, provide UX feedback, think about product integrations, manage a community, give presentations, build marketing messages, write blog posts and talk to customers. You’re not expected to be the world’s best engineer, or writer, or marketeer. You’re expected to know the most impactful 20% of each of those roles.

Engineering

As an engineer, it’s likely that you need to know your language in depth. You need to know the ecosystem, how to write unit tests, the best way to deploy your code. You need to know which package to depend on, and which to avoid. You need to ship robust code.

As a developer advocate, you have to ship a demo that works. It usually doesn’t even have to work in 6 months time. You’re showing a capability today.

Marketing

Working in marketing, you need to understand MQLs/SQLs, attribution, drip campaigns, marketing automation tools, copywriting, SEO and paid advertising.

As a developer advocate, you just need to know what messaging resonates with your target audience. There’s usually someone to help you get it out there.

Product

Being a product manager is a lot more involved than “tell engineering what to build”. You have to watch market trends, deal with customer escalations, build requirements documents and figure out pricing and packaging for your product.

As a developer advocate, you have to provide product feedback and suggest integration opportunities with other parts of the ecosystem.

Be a spider

You know more than most people about a wide range of topics. You know less than most people about their specific topic. Being a great developer advocate is about maximising the impact you can have with that 20% knowledge.

Be a spider. Get involved in as many cross functional initiatives as you can and help get the ball rolling. You can connect the dots in a way that very few other people can. Then once things are going smoothly, get out and leave it to the professionals. There are always more projects that need a hand to get started.

Show all issues for an epic in Confluence

2023-07-16T19:27:51Z

I’ve been working on go-to-market kits for large features recently, and needed to show all of the issues included in a specific epic on a Confluence page. It took me longer than I’d like to work out, so here’s how to do it:

Insert a Jira Issue / Filter
Use the filter "Epic Link"=EPIC-123 ORDER BY createdDate ASC , customising the epic name

That’s all there is to it. You can now see the progress towards your epic alongside all of your other information in Confluence.

Search for inactive users on Jira

2023-07-15T21:09:25Z

It’s unfortunate, but people leave teams all of the time. I inherited a team that had some turnover, and needed to get the backlog in to shape.

The first thing I did was to remove all deactivated users from tickets. It turns out that Jira allows you search for all members of a specific team. Combining this with assignee not in gives us the following:

sql
project = "MYPROJ" AND assignee not in (membersOf(jira-software-users)) AND status = Open ORDER BY created DESC

I also found it useful to find tickets raised by those no longer with the company to be triaged and closed if outdated:

sql
project = "MYPROJ" AND reporter not in (membersOf(jira-software-users)) AND status = Open ORDER BY created DESC

Removing outdated tickets that I couldn’t follow up on helped trim the backlog massively, and unassigning tickets from those that have left the team means that the backlog matches reality.

Providing both default and named exports in JavaScript

2023-07-15T21:00:29Z

I always wondered how some NPM packages provided a default export in addition to named exports. Something like this:

js
// Provide the most common use case
const validator = require("my-validator");
// Then you can use validator() or one of the components such as validateEmail()
// Validate everything in one
const isValid = validator(payload);
// Or validate specific things
const isValidEmail = validator.validateEmail(payload.email);

Then one day I was using nock to write some tests and noticed that they do the same thing:

js
const nock = require("nock");
nock.disableNetConnect();
const scope = nock("http://www.example.com")
  .get("/resource")
  .reply(200, "path matched");

So, I went digging in the code and found that it can be accomplished by setting module.exports to be a function, then using Object.assign to attach new method to the function prototype:

js
// my-validator/main.js
const validateEmail = require('./validators/email');
const validatePhoneNumber = require('./validators/phone');
const validateAddress,= = require('./validators/address');
module.exports = function(payload){
  // Do validation
}
Object.assign(module.exports, {
  validateEmail,
  validatePhoneNumber,
  validateAddress,
});

Now that I’ve seen it in action it makes total sense. Using named exports allows you to export useful functions from your package without people needing to require specific files (which you may choose to move in the future). Object.assign expands your public API, providing additional value to consumers but also additional maintenance burden to you.

Now you know how to expose multiple functions from a single package as part of your public API. Now, you just need to decide what you want to expose as your public API 😀.