DEV Community: Joe Mainwaring

Do you balance High-Tech with Low-Tech?

Joe Mainwaring — Tue, 25 Jul 2023 16:15:00 +0000

Technology today is an immersive experience, and as professionals in the space we tend to be above average in terms of our adoption and interconnectivity. Today we have an app for nearly every idea imaginable, providing significantly more value-add to our daily lives than the generations that preceded us. Technology however can be a double-edged sword, and the potential value-add and ease of access to so many options can lead to behaviors detrimental to our well-being. Doom-scrolling is a solid example of this, where apps have created such a focus on retaining attention that we spend an unhealthy amount of time glued to our screens.

In the early 2010s, I had come to this realization as I learned from the successes (and many, many failures) of my 20s, and actively began to seek out low/no technology counter-balances to foster healthier long-term personal growth.

For myself, these counter balances came in a variety of forms over the years, some that come to mind:

Note taking using Moleskine notebooks
Indoor gardening
Marathon training

Have you found yourself needing to counter-balance our technology-focused lives with low/no tech? Share your own experience and ways you've created a balanced lifestyle in the comments below ⬇️

Does anyone else have mixed feelings with remote work?

Joe Mainwaring — Tue, 20 Jun 2023 21:05:09 +0000

We hear a lot of backlash when prominent CEOs call for a return to office work culture, but I'm curious if others may feel opposite of the public sentiment?

I support the option for people to work remotely within an org if their roles and responsibilities can be performed asynchronously, but my personal preference has always been to operate in-office. That was taken away from me as a result of the pandemic as my company ended up shuttering the local office.

After spending these last 3 years working 100% remotely, I find myself with a renewed desire for a hybrid working environment. It's not an option with my current company, but I can't deny that it's what I think is best for my career progression. I'm far more effective with some in-person collaboration on a regular cadence. Do you share similar sentiment, or do you find yourself freed by remote work?

Let me know your thoughts in the comments below ⬇️

The Reddit blackout is a lesson in risk management

Joe Mainwaring — Fri, 16 Jun 2023 18:58:16 +0000

This morning I ran headfirst into the picket line for the Reddit Blackout which hindered some research I was doing into a technical solution.

While I empathize with the impact to indie devs and SMBs dependent on the Reddit API, I can't support the protest. Reddit's API is not a public good; we are not entitled to freely access it. While I could cite capitalist talking points to support my position, I'd rather focus instead on a different narrative, one which I suspect is underestimated by many indie devs and SMBs - risk.

Risk Management

Risk Management was originally defined as part of the ISO 31000 Standard and can be summarized as:

the identification, evaluation, and prioritization of risks, followed by coordinated and economical application of resources to minimize, monitor, and control the probability or impact of unfortunate events, or to maximize the realization of opportunities.

For mature technology companies like WorkTango, we are required to invest in Risk Management, and one way we meet this obligation is by maintaining an artifact known as a Risk Register. A Risk Register is a ledger which captures all of the criteria outlined in the definition of Risk Management. We add to this register as risks are identified, and engage in a quarterly exercises to brainstorm new risks. This provides the business as a whole with an understanding of potential risks for resource planning (feature development) and strategic decision making.

So why bring up risk management and the risk register in the context of the Reddit Blackout? If WorkTango was in the business of creating a client app for Reddit's platform, we would have identified Reddit's free API as a dependency risk.

Dependency Risk

Dependency Risk is a category of risk you take on whenever you have a dependency on something (or someone) else. When we build client apps wholly dependent on a third party platform, a dependency risk is created. That third party could cease operating, or as both Reddit and Twitter have demonstrated, stop giving away their resources for free.

Open APIs are free, as in beer

As a developer, it's best to think of Open APIs as free, as in beer:

The API resource (beer) cost you nothing
But APIs aren't free, somebody paid for the API (reddit)

The 2010s was a golden age in capital investment and the technology industry benefited significantly, enabling a lot of free resources as a draw to build audiences and engagement. However, the 2020s so far have proven to be more challenging. Money is no longer free and as a result, many companies are having to mature their business models to be more self-sustaining. This means reducing expenses and finding additional sources of revenue. Monetizing previously open APIs is an unfortunate intersection that addresses both needs. Expect less free beer on the internet as we progress through these tougher economic times.

Mitigating the Risk

The only way to mitigate a dependency risk is to add a layer of redundancy, but when you build apps on top of platforms like Reddit or Twitter; you can't fail over to a different platform to access the same content. So how would I mitigate this risk?

Accept that if this risk is realized, it's game over for the app. Since I do not own the backend which my app depends on, losing access to it means my app can no longer function. Draw up a plan to wind down the product gracefully in the event this risk is ever realized.
Diversify. If I can't prevent a game-over situation, the next best mitigation strategy is to diversify my revenue streams. That means building a second app on a different platform (ex: slack app), or building an app without the platform dependency risk. That way, if I lose one app, I take a financial hit, but hopefully the other app can support myself while a new app is conceived to replace the lost revenue.

Did you find this post insightful, or perhaps you disagree with my risk points in regards to Open APIs? Share your thoughts in the comments below.

Should AI development beyond GPT-4 be paused?

Joe Mainwaring — Wed, 29 Mar 2023 14:35:39 +0000

Leading AI academics and industry experts - including Steve Wozniak and Elon Musk, published an open letter today calling for a pause on developing more sophisticated AI beyond OpenAI's GPT-4. The letter cites risks to society and humanity as a major concern and asks for the pause to enable the industry to develop shared safety protocols.

Do you agree with the consensus of the experts? Is a pause even a realistic option when you factor in global politics and capitalism? Share your thoughts below!

I'm doing this one thing differently next time I build a SaaS product

Joe Mainwaring — Thu, 24 Nov 2022 20:56:59 +0000

As one does the further they progress in their career, they develop wisdom based on their experiences and apply it with future opportunities. When it comes time for me to build my next SaaS product, one piece of wisdom I intend to apply is to host my SaaS Product and Marketing Website on separate domains. Seems simple enough, but why is this a wise piece of advice? As products scale and businesses mature, the necessity to demonstrate the integrity of your product becomes more paramount.

Since Information Security falls under my domain as Director of Infrastructure for four B2B enterprise SaaS products, I regularly have to interact with external stakeholders: Customers, closing deals (sales), auditors, and even insurance providers. At least once a month, someone will conduct a due-diligence task on their end by publicly scanning my domains and confront us with the findings.

While I think it's important to address vulnerabilities, not all vulnerabilities are the same:

Some vulnerabilities are benign because your use case is not applicable
Some vulnerabilities cannot be reconciled as they were past decisions that are unable to be changed
But most importantly, some vulnerabilities create a liability for customer data, and others do not.

In my context, 99% of public probing does not identify vulnerabilities that meet the third point, but it's the only reason why the feedback is being given. And because people think they've identified a risk to their data, they're often times unwilling to accept the simple answer, instead sucking up my time through multiple interactions to effectively communicate our integrity. If I separate the marketing website from the actual SaaS product, I'm better positioned to deflect these reports, as I can instead encourage them to rescan the domain where the customer data is accessible.

So, for my next SaaS product, expect the following:

Marketing Website will be hosted with a .com address
SaaS product will live on another tld like .app, .io, etc

While I don't expect many of you to have encountered this type of situation, I'd welcome your thoughts or experiences if you do have similar.

A Bitter Interview Experience

Joe Mainwaring — Sun, 06 Nov 2022 19:54:31 +0000

Recently, I interviewed for a leadership role that left me bitter at the decision not to proceed. While I wasn't sold that I was the correct fit for the role, I felt that the decision was made prematurely given how the role was advertised. I won't name the company, but I'll generalize it as being of the moonshot pedigree with an extremely unique and forward-thinking business problem being solved.

What Went Wrong

The Job Description didn't cover the key technologies

As an interviewee, I rely on job descriptions to self-evaluate & prepare for interviews with different stakeholders. In my most recent experience, I found myself performing top-level discovery in both the hiring manager and technical interviews, leaving me unprepared to speak in regards to those technologies. If you know that you need to build out a data lake with a robust abstraction layer, or that you need to scale a tech stack component that's more unique to that industry, it's helpful to describe that with the advertisement. It's also helpful to stack-rank your priorities in the job description, as it intuitively emphasizes what you need most.

No Agendas

To put it simply, it is disrespectful in business to schedule a meeting without an agenda. That opinion applies equally to the interview process, as it doesn't enable one side of the meeting to adequately prepare. As an interviewee, going forward I will be asking for an agenda for every meeting. This will enable me to ask follow-up questions if I'm unsure of what a certain topic will be and come prepared.

The test didn't reflect the role

Competency tests are a common (and debatably necessary) part of the interview process, as it serves to be a filter around the necessary skills to succeed. But a lot of companies get it wrong and measure a candidate incorrectly, which is how I felt after this interview.

The test itself (Application Architecture Design) is a completely legitimate type of test when you're evaluating an individual contributor like a Senior or Principal engineer. But as a leader? I'm not being hired for ditch digging, I'm being hired to build successful teams that solve the company's problems. Yes, it's important I have a base level of competency, but when the role isn't that of an individual contributor, this kind of test is not a golden signal for evaluating a candidate.

How I would have done it differently as the interviewer

To start, I would update the job description to reflect what topics are going to be discussed during the hiring manager and technical stage interviews, and stack rank the priorities of each bullet point.

Second, Agendas. They don't even have to be complex agendas either, something as simple as the following works:

1.  Introductions 
2.  Pair session - Application Architecture Diagram
3.  Q&A

Third, I would design a competency test where the candidate pitches a solution & plan to implement. This would be a more appropriate way to measure a leadership role involving a vague problem & a budget to build a team. It wouldn't be a synchronous test, rather an assignment that would be issued after passing the hiring manager stage and submitted following the completion of stakeholder interviews.

Last but not least, I would re-organize the technical interview step into a round robin where a candidate meets with 2-3 stakeholders individually to evaluate competency. Preferably, the stakeholders would be from different teams/departments, enabling different perspectives & providing a more comprehensive evaluation of a candidate, reflecting the the fact the job isn't a single function.

Your Thoughts?

Do you empathize with my experience, have your own to pour on, or have differing opinions? Share your thoughts below in the comments section, but please keep it civil and agree to disagree ;)

Opening up my Open Source Projects for Hacktoberfest

Joe Mainwaring — Sun, 09 Oct 2022 15:34:16 +0000

Calling all beginners!

Are you interested in participating with Hacktoberfest, but find many of the projects a little complex to participate in? I have a couple opportunities for you!

NPM: Card-dealer

The card-dealer package was a simple package I created several years ago based on a coding test I had to take for a mid-level software engineering role. The runtime boasts no dependencies (only devDependencies!), but does with a curveball of a strict 100% test coverage requirement, but it could also be an opportunity to learn unit testing in a simple scenario!

Card Dealer is written in TypeScript and Markdown.

Participation Ideas

Add new decks to the package: My OSS package includes a standard 52-card deck and an Uno deck, but there are many other types of card decks out there! MGT, Pokemon, CAH, the list goes on. Lots of opportunity to be creative if you desire!
Add new dealer methods: So far I have implemented a core set of methods related to Dealer actions involving a deck of cards, but there may be more use cases with other decks.
Game Management: Currently, the scope of this package is exclusive to the actions around dealing cards, but I've contemplated adding more game management aspects to the package.
Add a feature that exits in a fork: Many forks exist because they required a slight variation to my implementation, which presents an easy opportunity to port those changes back!
Update documentation

Github Actions: Balena Push

Balena push is an open-source package that was born out of both need and opportunity with the introduction of Github Actions. At the time, I was using the IoT platform Balena.io to manage a fleet of Digital Signage (TVs with Raspberry Pis) within my company's office. The Github action enables you to continuously deliver your project to Balena by pushing changes to the platform.

Balena Push is written in Docker and Shell.

Participation Ideas

Pass Flags: Looking over the forks of my OSS package, I found that someone had forked purely to pass flags I didn't need when I authored the package. The linked ticket should help you get started.
Integrate further with the CLI: The Github Action itself just uses the Balena CLI to execute a push command. Take a look at Balena's CLI docs and if you see a way to extend, feel free to take a stab at it!
Add a feature that exits in a fork: Many forks exist because they required a slight variation to my implementation, which presents an easy opportunity to port those changes back!
Update Documentation

IoT: Digital Signage

Digital Signage is an open-source service that I put together to turn the Televisions around my company's office into useful displays for things like Activity Feeds (our own product) and Operational Dashboards (Datadog).

Participation Ideas

Update documentation: So I have a confession to make - I didn't write any docs for this project. I usually overlook this one when I talk OSS, but it is public and the project can be forked and reused by others. While the lack of a README is typically a barrier for participation, the project was born based on tutorials. Google balena-wpe to find numerous guides around the actual service driving the project.
Update the subpackage dependency: As mentioned above, my digital signage uses balena-wpe as a sub module, but hasn't been updated in ages. This is a good opportunity if you want to sharpen git skills.
Enhance the github project: Since I have overlooked this as OSS in the past, it doesn't have a lot of the enhancements I've made to other projects. I discuss many of these in my post How I maintain OSS, and several of these can be direct copies from the files I've added to my other OSS packages listed above.

Need Help?

Do you want to participate but not sure how to get something across the finish line? Open a Pull Request and we'll begin a discussion to help get your PR in an acceptable state to be merged. You may also DM me on Hacktober's Discord Server under the name mainwaring

Got an idea I didn't mention above? Start a conversation as an Issue.

Describing My Sandbox

Joe Mainwaring — Mon, 03 Oct 2022 15:25:05 +0000

I've been busy this year executing my take on the #100DaysOfCode challenge by rebuilding a set of development skills that I can use to implement products using micro-services. That work has resulted in a rather robust mixed-use sandbox. As part of my effort to build out a comprehensive public documentation portal, over the weekend I set about starting a document to describe my Sandbox's Architecture. Below is the first architecture diagram I've produced, describing from a top level the services which make up my sandbox & how they're zoned or organized:

Using Cloudflare's amazing DNS service, my Sandbox is spread across two domains:

Knowhere.space: Knowhere is my edge-computing zone, with the DNS routing to a NAS server or Raspberry PIs within my home. I use this zone to serve content primarily within my home, as well as services which are either experimental, or cost-prohibitive in the cloud.
Mainwaring.dev: Mainwaring.dev encompasses all of my cloud computing services from a variety of different providers, including DigitalOcean, Vercel, Carrd.co and others.

Knowhere.space

Traefik: Traefik acts as an ingress for my homelab, enabling me to route traffic to the other services I have running on the edge without overly exposing my Firewall with open ports.
PiHole: PiHole is a DNS Sinkhole I added to reduce the number of ads and trackers served to devices on my local network.
Plex: Plex is my personal Netflix, serving content I have stored on my local network.
YAC Reader: Comics are a guilty pleasure of mine, and YAC Reader enables me to serve digital comics to my iPad with ease.
Transmission: Transmission is a BitTorrent client. The specific implementation of Transmission I use includes OpenVPN, allowing me to securely route that traffic.
Lighthouse: Spotify's open-source Lighthouse Audit Service integrates my Backstage.io implementation with Google Lighthouse. In a for-profit situation, I would run this service in the cloud, but I'm taking advantage of existing resources I have to run such a minor service.

Mainwaring.dev

API: A very robust REST server built using the @strapijs. I currently have over 1 million records of personal data stored from more than dozen sources, including third-party services (Twitter, Facebook, Discogs), manual data entry (press releases & news articles, postcards) and Apple's Healthkit (Workouts, Calories Burned, Heart Rate).
Backstage (server): Backstage is an open-source project from Spotify which enables teams to build developer portals and customize them in a way to aggregate data from all the various tools a team uses.
Chartbrew (server): Chartbrew is open-source reporting service which really makes it easy to visualize data.
Backstage (website): The Backstage Frontend is a separate process from the backend, so I opted to host it on Vercel.
Chartbrew (website): Similar to Backstage, the Chartbrew frontend is a separate process which I host on Vercel.
Contact: While it's awesome to build cool things, sometimes you just need a simple website tool for static content. Contact is one of these examples. This branded-alternative to LinkTree is used as a digital business card, providing my audience with a list of options to learn about myself and make contact.
The Legend of Bruce: A marketing website for a social experiment. When I attend music festivals, I typically bring a large inflatable dinosaur (Bruce) to crowd-surf a headlining act, and at the end of the night he always goes home with a random person he found in the crowd. Bruce now includes a QR code linking back to this page, which serves as a Call to Action to share pictures or videos people take with Bruce on Instagram.
Status Page: Status Pages are a common feature for SaaS products, and BetterUptime made it really easy to implement monitoring over my resources.
Public Documentation Portal: Gitbook enables me to author public documentation within my Github Project and easily serve it in a presentable way. I use this portal to share documentation for open-source projects I publish, as well as Architecture documents and how-to guides.

Do you have questions or comments about my sandbox so far? Drop them below ⬇️

Having fun with old work domains

Joe Mainwaring — Thu, 29 Sep 2022 22:01:33 +0000

Today I executed on a silly idea involving a domain I'm retiring at work, highground.com. Highground was the brand I joined back in 2014, and in 2018 we were acquired by a Private Equity firm and merged with a competitor, creating the company that is now known as WorkTango. For those of us who are Star Wars fans, there is an infamous clip from Episode III: Revenge of the Sith

Since I have the Highground, it was only natural to share it with everyone (except Anakin, of course), enjoy!

https://ihavethe.highground.com

Who still uses Grunt.js?

Joe Mainwaring — Fri, 09 Sep 2022 13:09:34 +0000

Grunt.js is a favorite tool of mine, while it's most commonly viewed as a (legacy) build system, I've found it to be a fairly robust CLI framework for designing local and automated tasks and still actively develop tasks to this day.

I've thought about writing content around these other use cases, but I've been hesitant knowing that it's not widely popular given other build-focused tools available.

If you use Grunt.js, or would be interested in how one could use it beyond build steps, share your thoughts below in the comments.

How to use 1Password to share local secrets

Joe Mainwaring — Fri, 02 Sep 2022 17:13:01 +0000

Author's Note: All the plain-text secret values shown in this tutorial are fictional. Don't try to use them to hack my things, because these resources do not exist.

1Password is an excellent password manager, and recently I began exploring the value it can provide for secrets management, and boy is it easy! If your team is using 1Password, you can use your vaults to share secrets and pass them to your projects! Below is a tutorial I've documented as I tested this process myself.

Prerequisites

In order to follow this tutorial, you'll need:

A 1Password cloud subscription. If you're using the legacy version of 1Password where you self-host your vaults, this guide likely won't work.
The 1Password CLI. You can find the installation docs here.

Optional: Create a vault

While this step is optional to complete the tutorial, it's a good practice to have your secrets and credentials organized in a way that segregates access. For this example, let's pretend our project is the following:

JavaScript based SaaS Application
Engineering Team:
- 1 Principal Engineer
- 1 Senior-level Engineer
- 1 Junior-level Engineer (Contractor)
Two Environments
- Non-Prod: Everyone has access
- Production: No contractors

Given this context, we'd want our Junior Engineer to be able to view/add/edit non-production secrets, but not production ones. Let's start by first creating a vault which is accessible by all engineers and call it NewApp Non-Prod:

Add secrets to vault

Next, let's populate a few different credentials in this vault. For this tutorial, I'm going to keep things simple and create two different items. For our first item, let's create NewApp (Local). This is where I would put shared secrets that are owned by the application itself. In this example, I've defined a few items like URL, admin password, postgres connection string, token salt, and JWT Secret:

Next let's add a second item to our vault for a third-party integration. For this example, we'll use the service Twilio and define our test Account SID and Auth Token which is used by the application at startup:

Create a .env-template file

Within your project, create a new file called .env-template, which we'll use as a template for creating a .env file used by the application at runtime. Let's scaffold our template by mapping out the environment variables our application requires:

1Password CLI

Now that we have our .env-template scaffolded, let's shift our focus towards the 1Password CLI. First, start by authenticating our CLI with the command eval $(op signin). The CLI will ask you to confirm which account you're authenticating with, and you'll be prompted to provide your password.

Once you've authenticated, you'll want to first start by listing your Vaults. To list your vaults, execute the command op vault list:

Now that we have our vault details, let's list the items of our NewApp Non-Prod vault. To list items in a vault, you'll execute the command op item list --vault <vault name or guid>:

Finally, we'll tell the CLI to fetch us the details of an item in JSON format, so we can copy the reference pointer to our template. You can achieve this wit the command op item get <item name or guid> --format json

The reference pointers will be formatted as either
op://<vault>/<item>/<property> or op://<vault>/<item>/<section>/<property> depending how you stored the secret in your item. The different paramaters can either be that property's label/title/name or guid.

example-project % op item get 'NewApp (Local)' --format json
{
  "id": "bzbaer6g2smaqqpntup3zugy3y",
  "title": "NewApp (Local)",
  "version": 1,
  "vault": {
    "id": "54wvogqhltjzolqik3f4cajpru",
    "name": "NewApp Non-Prod"
  },
  "category": "SERVER",
  "last_edited_by": "LFQSVNLW5VCBFDW6QKJRODDWFY",
  "created_at": "2022-09-02T14:50:19Z",
  "updated_at": "2022-09-02T14:50:19Z",
  "sections": [
    {
      "id": "admin_console",
      "label": "Admin Console"
    },
    {
      "id": "n3n3xpw3j5e4e22a6c26kqbuaq",
      "label": "Secrets"
    }
  ],
  "fields": [
    {
      "id": "notesPlain",
      "type": "STRING",
      "purpose": "NOTES",
      "label": "notesPlain",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/notesPlain"
    },
    {
      "id": "url",
      "type": "STRING",
      "label": "URL",
      "value": "https://localhost:42069",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/URL"
    },
    {
      "id": "admin_console_url",
      "section": {
        "id": "admin_console",
        "label": "Admin Console"
      },
      "type": "STRING",
      "label": "admin console URL",
      "value": "https://localhost:42069/admin",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Admin Console/admin console URL"
    },
    {
      "id": "admin_console_username",
      "section": {
        "id": "admin_console",
        "label": "Admin Console"
      },
      "type": "STRING",
      "label": "admin console username",
      "value": "admin@newapp.dev",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Admin Console/admin console username"
    },
    {
      "id": "admin_console_password",
      "section": {
        "id": "admin_console",
        "label": "Admin Console"
      },
      "type": "CONCEALED",
      "label": "console password",
      "value": "eZMvXEcKTL9KWRjhyTrN",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Admin Console/console password"
    },
    {
      "id": "izfxzz7i5qbtj7unkkh6nfg3hu",
      "section": {
        "id": "n3n3xpw3j5e4e22a6c26kqbuaq",
        "label": "Secrets"
      },
      "type": "STRING",
      "label": "Postgres Connection String",
      "value": "postgres://postgres:123456@127.0.0.1:5432/dummy",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Secrets/Postgres Connection String"
    },
    {
      "id": "6ljbsngcsimhqg7x4iukfbaovm",
      "section": {
        "id": "n3n3xpw3j5e4e22a6c26kqbuaq",
        "label": "Secrets"
      },
      "type": "STRING",
      "label": "Token Salt",
      "value": "07af136084ca0ea0cc192b0769e97122",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Secrets/Token Salt"
    },
    {
      "id": "bvbjgzmdo4wwra7noxfnsvvyca",
      "section": {
        "id": "n3n3xpw3j5e4e22a6c26kqbuaq",
        "label": "Secrets"
      },
      "type": "STRING",
      "label": "JWT_Secret",
      "value": "061971eaaaa99212e737c1e789799cd8",
      "reference": "op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Secrets/JWT_Secret"
    }
  ]
}

Add reference pointers

With the reference value copied, return to your .env-template file and paste the pointer as the environment variable value. Repeat the process of fetching the reference values until your .env-template file is complete. What mine looked like after I finished:

ADMIN_PASSWORD=op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Admin Console/console password
POSTGRES_CONNECTION_STRING=op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Secrets/Postgres Connection String
TOKEN_SALT=op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Secrets/Token Salt
JWT_SECRET=op://NewApp Non-Prod/bzbaer6g2smaqqpntup3zugy3y/Secrets/JWT_Secret
TWILIO_SID=op://NewApp Non-Prod/Twilio/Test Secrets/Account SID
TWILIO_AUTH_TOKEN=op://NewApp Non-Prod/Twilio/Test Secrets/Auth Token

Inject your secret values

Now that we have our .env-template fully configured, we can run the command op inject -i .env-template -o .env which will create a .env file with the secret values. In the screenshot I have below, you can compare the template against the output of the command:

Add Project Shortcut

Now that you have a process to easily generate your .env, let's make it easy for other team members to use by scripting the process. Since we're working with a JavaScript project for this tutorial, let's add a script to our package.json file so developers only have to run npm run env:generate to create their own .env files locally:

{
  "name": "@mainwaring/example-project",
  "version": "2022.1.0",
  "description": "This is my example project!",
  "main": "index.js",
  "scripts": {
    "env:generate": "eval $(op signin) && op inject -i .env-template -o .env",
    "test": "jest"
  },
  "author": "Joe Mainwaring <joe@mainwaring.dev>",
  "license": "MIT"
}

You'll notice in this example, my script is eval $(op signin) && op inject -i .env-template -o .env and not just op inject -i .env-template -o .env. By chaining the signin and iject commands, the developer will be be immediately presented with the signin workflow if they aren't already authenticated. This would otherwise require the developer to run 2-3 additional steps on their own if their terminal session was unauthenticated.

And that's it! You now have a team using shared secrets managed through 1Password! Share your experience with the tutorial below in the comments.

How I Maintain OSS Projects

Joe Mainwaring — Thu, 01 Sep 2022 18:55:40 +0000

Earlier this week I posted a rant about how a Pull request I authored for an Open Source package went un-reviewed for over 2 years. It wasn't a post I was particularly fond of given it was born out of frustration, but the moment had me self-reflect on my own OSS Projects and revisit them. Those check-ins resulted in several enhancements to the projects and their workflows, designed in a way which should foster constructive interactions with community members using my software. And now, I'm sharing those changes here with you to consider for your own OSS projects:

Project Configuration

There are a plethora of ways to configure and automate workflows around your project that are freely accessible to open source projects. Several ways I set up my projects:

Dependabot

Dependabot helps me spend less time maintaining my projects by automating dependency updates as pull requests, making the process of keeping dependencies up to date significantly less time-consuming. In addition, Dependabot can surface vulnerabilities, something that can easily get overlooked by package maintainers.

Templates

When it comes to fostering constructive dialog and efficient workflows, Templates bridge the gap between you and your audience.

Issues

Not only can you provide a template for issues, but you can provide a contextual template based on the type of issue filed. So far for my projects, I've kept this configuration relatively simple with Two types of issues: Bug and Feature Request. The Bug template asks evidence-gathering questions to help troubleshoot issues, while the Feature Request template will have questions related to scoping a User Story.

Pull Requests

Using Pull Request templates, I'm able to provide would-be contributors with a guide for submitting their pull-request in a state that can be easily accepted. Using the template, I'm able to provide the contributor with questions to answer and a checklist to signal the PR would meet general Acceptance Criteria - like test coverage or style.

Documentation

Since OSS is by it's nature, self-service, it's important to have the right kind of documentation for the project. Not only should a participant know how to use your project, they should also have resources on how to contribute to the project, should they choose to. Documents I have in my projects:

README.md

While you could derive how to use open-source without documentation, adoption does depend on a singular How-To guide to implement. README.md is a common document found in the majority of open source projects today, and should deliver some key content:

A getting started section which describes installation steps and a basic implementation
A dictionary which describes methods, inputs, or outputs
Citations & Reference Links

Contributing Guideline

If your README.md file is small, you may opt to include this section there, but it's probably more practical to just approach this as a separate document.

Contributing Guidelines are used to describe how someone can participate with the project. It should describe both discussions and code contributions. Things you would include as Contributing Guidelines:

If the contributor has to sign a Contributor License Agreement (CLA). (Only add one of these if it's been recommended by your legal counsel).
Community standards, like the type of language that is permissible in discussions (ex: no targeted harassment)
Style Guide for making code changes
Workflow process (Example: An Issue must be approved before a PR will be accepted)

Github Actions

Github Actions provides my projects with an easily configurable CI/CD solution to automate different steps of my project workflows. Below are several actions I frequently use:

Build & Test

I consider these two basic steps that nearly every OSS project has. Having these as Github Actions is a requirement for enabling larger workflow automations for a project. For example, if my OSS Project has sufficient test coverage, I could automate the acceptance of Dependabot Pull Requests that pass the Github Action.

Publish/Deploy

Another common automation is for an OSS package to be published or deployed. By scripting out the process, a maintainer can reduce the human interaction to push updates for their software.

Stale Janitor

What I love about the actions/stale GHA is that it performs cleanup tasks for my Issues and Pull Requests. If either has no new activity for 30 days, a Stale label is applied and a comment added warning that the item will be closed in 30 days if no new activity happens. After 60 days with no activity, the action will automatically close out the item and append an additional message.

Fork Sync

On the off-chance my OSS Project is a fork of another project, I have a Github action which will automatically create pull requests when the parent project is updated.

Depending on how much I've altered my fork, being able automatically sync downstream changes has significant maintenance benefits, as it basically transfers the responsibility back to the parent package.

Code Coverage

Depending on the quality level of my OSS project, I may have a strict 100% test coverage policy for any contributions. While I don't need a third-party service to enforce such a rule, having a GUI-friendly interface is helpful when reviewing coverage reports. There are several third-party dependencies that offer code coverage reporting, and many of them are free for public open source projects.

Alerts

I'm a big fan of Slack for work, so I set up my own "sandbox" instance mainwaring.slack.com. I'm the only member of my org, instead of using it for social communication, I use it to aggregate events from third-party services like Github. This allows me to have a #open-source-projects channel where notifications will surface when new activities occur, like an Issue being reported or a Pull Request being submitted.

Routine Check-ins

One more informal process I do is to check in on my projects in a routine manner, typically at least once a year, but possibly more frequently if any of my OSS projects had higher traffic. Tasks I do at check-in include:

Decide if this project should be archived or not.
Review any outstanding issues or PRs and make decisions so the items can be closed out.
Dependencies and Vulnerabilities
- Enable Dependabot if not already configured
- Apply any outstanding dependency upgrades
- Review vulnerabilities and make InfoSec decisions
Review Forks of project: Forks often times are slight modifications to a project, this can give you inspiration as to what features you are missing with your project.
Review Documentation
- Update language as needed to improve communication
- Add enrichments like badges or multimedia to communicate project details
Review CI/CD
- Add workflow automation steps as identified
Publish a new version