Forem: Ricardo N Feliciano

Introducing para: A package metrics tool

Ricardo N Feliciano — Tue, 11 Aug 2020 16:00:00 +0000

para is short for Packages and Releases Analytics. It's a simple tool to solve a simple problem for those who release software via Snaps, Brew, GitHub Releases, etc. Metrics and availability.

If you release software via Brew or GitHub Releases, para lets you view metrics from those platforms so you can see how well those packages are doing. Here's an example of pulling the metrics for the static site generator Gotham:

Brew data:
The number of installs in the last 30 days is: 4

GitHub data:
v0.6.0:
gotham-v0.6.0-linux-amd64-checksum.txt: 0
gotham-v0.6.0-linux-amd64.tar.gz: 2
gotham-v0.6.0-macos-amd64-checksum.txt: 0
gotham-v0.6.0-macos-amd64.tar.gz: 3
v0.5.0:
gotham-v0.5.0-linux-amd64-checksum.txt: 0
gotham-v0.5.0-linux-amd64.tar.gz: 2
gotham-v0.5.0-macos-amd64-checksum.txt: 0
gotham-v0.5.0-macos-amd64.tar.gz: 0

Don't have a software project yet? No worries, para is still helpful for you. When you're still in the naming phase, para check will check if a name is available on Snap, Brew, Chocolatey, and NPM. This way you can easily find a name that's available without hacking to tack on a username or some other weird suffix to your project's name.

para is still very much a work-in-progress with only an unpolished v0.1.0 release so far. Snap metrics isn't yet supported but it's on the roadmap. It's written in Go, packed as a raw binary, deb and snap, currently supports Linux and macOS on amd64, and is open source (MIT licensed).

You can learn more and contribute at its GitHub Repository.

CircleCI is used throughout the Galaxy

Ricardo N Feliciano — Tue, 05 May 2020 00:14:01 +0000

Introducing DocsThursday: A Monthly Documentation "Party"

Ricardo N Feliciano — Thu, 07 Feb 2019 17:49:17 +0000

I love open source documentation and if you're reading this, maybe you do too.
I have a personal mantra of "Inspire, Educate, Motivate" and documentation fits right into that.
Documentation allows us to educate others to a near infinite scale.

You know, I partially owe my career to the free and accessible Linux server documentation that is available on the Linode Docs website.
I'm a die-hard Ubuntu user but I can't tell you the countless times the Arch Linux Wiki has helped me out of tight spots.

Docs are invaluable.

I want to motivate more people to contribute and learn from one another on how we can make better contributions and better doc websites.
DocsThursday is a party, campaign, workshop, or whatever you want to call it to create and contribute to open source documentation on the 3rd Thursday of every month.

Why DocsThursday?

There's nothing special about Thursdays.
I could have done a Docs Wednesday or Friday but it wasn't as catchy and we all know Tuesdays are for tacos.
So Thursday it is.

DocsThursday is inspired by DigitalOcean's Hacktoberfest, 24 Pull Requests, and most importantly, Write the Docs's Writing Day.
I'm trying to take the energy and productivity of Writing Day and replicate it more frequently at meetups local to you, with your co-workers within your company, and even online as a hackathon.

Let's take 30 minutes, an hour or even more, just once a month in order to give some love to open source documentation.

Interested? Check out the website, DocsThursday.com.

Would you like to help out?

DocsThursday is brand new and I'm still figuring out what to do with it.
The website is open source and built with Hugo.
Feel free to open PRs to improve the website or open Issues to ask questions or start discussions.
You can also start discussions/ask questions here in the comments or message me on Twitter.

If you've had these feelings or similar ideas, speak up!
Let's do this together. 😄

P.S. The first DocsThursday is February 21st.
I run the Write the Docs NYC meetup and we're hosting an event in New York for DocsThursday.
If you're around, check it out.
If you're not, start one in your area on the 21st and I'll list it on the DocsThursday website for people to find.

Hey open source maintainers! Empower your contributors with continuous integration

Ricardo N Feliciano — Tue, 04 Dec 2018 17:00:00 +0000

Surprisingly, many open source projects don't implement a continuous integration (CI) solution. Perhaps your project is one of these. You might be thinking, "We don't need it, we know what we're doing," or even, "We're too small, we'll implement it later."

When maintainers do use CI, it's often an insufficient implementation, such as using it for deployment without any testing.

I should know; I've been guilty of this myself.

But I want to show you that the decision to implement CI for an open source project is not about you. It's about providing the right tools for contributions. It's about enabling your project growing steadily with healthy code.

Using CI in your open source projects will help empower your contributors to make better PRs more easily and help your project grow and thrive.

Read on for four ways that CI can empower your open source contributors:

1. CI will actually run tests

This may seem obvious but it's quite important to mention.
Maintainers that have invested time in thinking about testing for their project need to convey that to potential contributors.

How? You could remind people to run tests:

In README.md
In CONTRIBUTING.md
Or in a Pull Request (PR) template

But even with those steps taken, how many people will actually read them and follow through? Running a project's tests with a CI provider like CircleCI means you don't have to worry about a contributor being lazy or forgetful. It's a safety net for the quality of your project's code.

2. CI build failures are okay; use them as a teaching point

It can be intimidating to contribute to an open source project for the first time. Let contributors know that PRs are welcome, but more importantly, that they don't need to get it right on the first try. If a PR status check turns red, great! The first thing you can do is make sure users know how to click over to the CI provider and check for the error (the test passing/failing link in the footer of a PR). Don't assume anything. Then you can give that person advice on how to fix the issue and give them time to do so. The idea here is that this is a teaching point. Remember: they may not knock out bugs at the same pace as you can. The contributor can learn and become stronger while this interaction sets the tone for your project and its community. Be friendly and fix things together.

3. CI allows contributors to work on projects they may otherwise not be able to

I'll explain this one with a real-world example. Let's look at the CircleCI CLI, an open source project that is compiled for both macOS and Linux. If a user was to report a bug that specifically affects the macOS build of the CLI I could try and fix it. As an Ubuntu Linux user, I can write the code and even cross-compile, but I can't actually test it to make sure the fix works. I don't have macOS.

Enter CircleCI.

I can open a PR with my fix and CircleCI will build and test it on a macOS machine. It has removed a technical barrier for me. Likewise, CI can lower friction for people wanting to open PRs on your project.

4. Don't require build secrets for non-deployment jobs

When API tokens, SSH keys, etc. are involved in a build, you don't want those build secrets getting into the wrong hands. This is understandable. Public projects on CircleCI have secrets turned off on forked PRs by default.

We've got your back.

What you can do is make an effort to allow forked PRs to reach a green build without those secrets in the first place. Commands that rely on secrets should be isolated to their own jobs or blocked with Bash logic. This way an outside PR will be able to run tests that pass and a project maintainer can come along and run integration tests or deployments in the master branch or some other way.

Conclusion

An open source project equipped with a CI tool lowers the barrier to entry for contributions while raising the overall quality. Open source is as much about the people as it is the code. Empowered contributors are happier and more productive. This benefits the project which means everyone wins.

P.S. CircleCI gives all users/projects a free build container. Did you know that we give open source projects, specifically, 4 containers? Still for free. Let's build software together!.

Level up go test with gotestsum

Ricardo N Feliciano — Wed, 21 Nov 2018 02:19:25 +0000

Hey Gophers!

One of the many great things about Go (Golang) is how simple it is to run tests. With the changes we saw in Go v1.11, running tests is as simple as:

# To test only your current module
go test ./...

# To test your module as well as its direct and indirect dependencies
go test all

In this post, I'm going to show you how we can make the output of go test more useful for local development as well as for CircleCI.

gotestsum

gotestsum is a CLI tool written in Go that runs go test for you. It enhances the output, making it much more palatable. As described on its GitHub repository, it "runs tests, and prints friendly test output and a summary of the test run."

Here's how it looks:

That's pretty cool for local development, but what about using it for continuous integration (CI)?

CircleCI / JUnit support

Most CI providers support saving tests results in the JUnit format. What the CI provider does with it can vary, but this usually means accessing historical test data, cool charts and graphs, etc. CircleCI supports collecting test metadata as long as it's in JUnit format. Since go test doesn't output in the JUnit format natively, we'll use gotestsum to do that for us.

gotestsum --junitfile unit-tests.xml

The command above will output your test results in the JUnit format. You can then tell CircleCI to use that file as test metadata via your CircleCI config.xml file.

    - store_test_results:
        path: /tmp/test-results

Installing gotestsum

Requirements

Go v1.10 or later

Installing locally

As with most Go applications, running gotestsum can be as simple as placing the binary on your $PATH:

curl -sSL "https://github.com/gotestyourself/gotestsum/releases/download/v0.3.1/gotestsum_0.3.1_linux_amd64.tar.gz" | sudo tar -xz -C /usr/local/bin gotestsum

The above command installs v0.3.1 of gotestsum, the most recent version as of this writing. If a new version is available, update the version number in the URL. You can also replace linux in the URL with darwin for macOS users. The binary packages available are for 64-bit x86 systems. See the next section to compile your own.

Compiling a binary

If you have a 32-bit system, ARM, or some other need, here's how to compile and install a custom binary:

go get -u gotest.tools/gotestsum

Installing on CircleCI

If you are using a Golang CircleCI Docker Convenience Image (circleci/golang) then congratulations, gotestsum is already pre-installed for you! If not, I'd suggest following the installing locally instructions and applying that to your CircleCI config.yml file or, for a custom image, within a Dockerfile.

gotestsum is a project maintained by Daniel Nephin, an engineer at CircleCI.

Blog Posts vs Docs - Where to Place Content?

Ricardo N Feliciano — Mon, 29 Oct 2018 14:10:10 +0000

Whether it's with a co-worker or someone I meet at a meetup, I tend to discuss one of three topics:
Open Source, Community, or Documentation.
When we talk docs, we end up talking Developer Relations / Advocacy, and content generation.
Time and time again I've been asked the same question:

“How do I know if X should be a blog post or a Pull Request (PR) to documentation?”

It's not a simple question because it can depend on your company's/project's culture and the audience you have.

That being said, I've answered this long enough times that I've put together questions you can ask yourself to determine where content can live.

Is this commentary?

If you're writing about software and you're providing lots of opinion or hype, it should be a blog post.
Commentary doesn't belong in documentation.

For example, early in 2017 I wrote a post for CircleCI called Why Developers Are Moving to Yarn.
This post covered some of the technical abilities for both Yarn and npm, observaton research, and yet it was a blog post.
This piece of content was a blog post because I was providing my opinion on why there was a lot of momentum swinging over to Yarn.
I was capitalizing on active discussion in the blogosphere, which leads to the next question to ask yourself.

Is this current events or news?

If you're writing about a new release of software, a feature that launched, or an impending End Of Life (EOL), it's a blog post.
Of course, your documentation should cover the details of a new feature, but if you're announcing it with language such as, "this week feature X is now available", it should be a blog post.

Notice how blog posts normally have a published date and docs don't.
This is because blog posts should be "timely".
Some clever marketers will remove dates from their blogs to make their content appear evergreen.
Don't do that, you're usually providing outdated information to the reader which isn't right.
No body wants to read a newspaper from two months ago.

The next two questions are probably the best distinctions between blog posts and docs.

Do I want to maintain this?

For both CircleCI's blog as well as my own, the most common type of post I make are guides / tutorials.
I like to teach things.
I believe these kind of posts can easily live in either a blog or documentation.
The big question is are you (or a team) going to maintain it?
The best way to explain this is with an example.

Let's say you write a blog post for ACME company on how to integrate ACME's product with WordPress.
Great, people may find it useful but the catch is WordPress is an active project.
Inevitably the software will change, especially with regard to internal plugin APIs or external APIs.

The guide you wrote can be invalid a mere few month later if WordPress happens to change something.
I believe that content in documentation should always be maintained.
If you write it, maintain it.
If you accept a PR from a contributor, you now are responsible for maintaining that guide.

If you plan on maintaining a guide, make it a doc.
Otherwise, make it a blog post.

Am I writing about the "why" or the "how"?

Content that is information heavy and contain all the steps on how to do something is a doc and belongs in documentation.
Diving into the why a feature works a certain way or why certain decisions were made tend to make for great blog posts.

In my experience, people tend to visit docs in order to get started with a product or when they're having issues and they need a reference or user manual.
They're in need of something specific so having content that is to the point with a high signal to noise ratio is very helpful.

Blog posts tend to be reserved for when a person's in learning or discovery mode.
They likely have time to read more "fluff" if it's entertaining, adds to their education, or adds more context for a better understanding.

Content Reusability

There's no rule saying you can't make both a blog post and a doc!
The most efficient Content Marketers and Developer Advocates do just that.

Much of the content I create comes from working on a demo or a side projects.
I take that code, experience, and learnings, and I distilled it down to it's core.
I then make a version of it that would be useful as a blog post and then a version of it that would be useful as a doc or an addition to an existing doc.

The same content can exists in multiple places.
Just cater your approach and language.

Summary

Ask about your content...

Is it commentary?
- Yes - it's a blog post
- No - it's a doc
Is it current events or news? Is it "timely"?
- Yes - its a blog post
- No - it's a doc
Are you going to maintain it with updates?
- Yes - it's a doc
- No - it's a blog post
What are you writing about?
- The "why" - It's a blog post
- The "how" - It's a doc

Would a Nonprofit Twitter Clone Work?

Ricardo N Feliciano — Wed, 24 Oct 2018 15:34:14 +0000

Many people have said that Facebook has gotten so big it should be considered a public utility.
I think this applies much more so to Twitter given the penetration and speed a single tweet can achieve for both local and global news.
Forget major cities and tech hubs, even the most remote parts of the world get their news via tweets.

This utility-like nature has been threatened and damaged many times before by decisions Twitter has made.
Some of these decisions due to what's in their best interest as a for-profit business.
They have an obligation to make money, I understand.

But what if they didn't?

Many, many, many (did I say many?) people have attempted to make Twitter clones.
In the scope of this blog post, I see two large problems with these clones.

They are for-profit startups. Or worse, not businesses at all. Too many VCs have invested money in Twitter to want to let it fail now by investing in a competing project. Also, being for-profit brings the same troubles Twitter has now. Balancing privacy concerns and user freedom with the need to make a buck.
Many "clones" aren't really clones anyway. These projects tend to create their own take on Twitter. That's fair, that's their right as makers and entrepreneurs. Personally, I mostly like the way Twitter works and would like an exact clone. It's gotten as big as it has for a reason, right?

So can we do it?

How possible would it be to create an identical Twitter clone, where the backing company is a nonprofit or foundation?
Where making money isn't one of the underlying goals but instead a sustainable communications and news platform for the world is?

If I remember correctly, one of Twitter's largest problems in the past as been scaling their infrastructure.
That remains an issue and for a nonprofit, paying for that infrastructure will be as well.

Still, I'm excited about the thought of cloning Twitter into an actual, public, technology infrastructure.
Even if it's just a pipe dream.

Install the Linode CLI on Linux via Snap

Ricardo N Feliciano — Tue, 23 Oct 2018 21:38:33 +0000

If you run a Linux distribution (distro) and you want to install the brand new Linode CLI, here's an easy and safe way to do so via a snap package.

Back in 2017 Linode announced their new v4 API.
This new API (still in development I believe) puts the old one to shame.
It's much more "RESTful" than the old one and enables many more features that the old one simply didn't have.

Building on the shoulders of the new API came the new Linode Developer Website, the new Linode Manager Preview available at https://cloud.linode.com, and of course, the new Linode CLI.

The new Linode CLI, written in Python, is very useful.
Its features and how to use them are detailed via Linode Docs.
While it can be installed via pip, if you don't already have pip installed or want a more secure way to run the CLI, you can install it via a snap.

You can install the linode-cli via snap for Ubuntu 16.04, Ubuntu 18.04+, elementary OS 5, Debian 9+, Fedora 28+, and more:

sudo snap install linode-cli

As with all snaps, it will be auto-updated and sandboxed from the rest of your system meaning secure.
More information on why you should be using snaps here.

The source for this snap can be found here while the source for Linode's CLI itself can be found here.

Automate GitHub Releases with CircleCI

Ricardo N Feliciano — Mon, 01 Oct 2018 16:56:01 +0000

This article was originally posted on CircleCI's blog.

Releases is a GitHub feature that allows you to present significant snapshots of your code, marked with a git tag, in GitHub's nice UI. If you're not currently using releases, I want to show you why you might want to, and how to implement them automatically.

With releases, you get what tags provide--a version number and description--but you also get a longer section for release notes and a place to store and display release artifacts. This means your software's binary, .deb, .rpm, and AppImage files will be hosted by GitHub for each release, providing a convenient place for users to install your software.

In this post, I will show you how to create releases within CircleCI. For a more general overview, see GitHub's doc on creating releases.

At its core, GitHub Releases is simply a GitHub feature layered on top of git tags. Let's break it down:

Git tags

Git tags give you a version number to mark a specific git commit as well as a short description. Believe it or not, just pushing a git tag to GitHub will create a new release in the "Releases" tab of your project on GitHub. This is a barebones release that includes only the tag information.

Releases

Releases add to git tags by providing a longer, "rich" description, the ability to mark the tag as a normal release or a pre-release, and most importantly, the ability to upload artifacts such as binaries for that release. Uploading these artifacts from CircleCI is what we're going to walk through here.

Tools

There are a few ways to publish artifacts from a CircleCI build to a GitHub Release:

manually with curl and the GitHub API
using GitHub Release
using GotHub (a GitHub Release fork)
and using ghr, which is what we'll use in our example

Using ghr

The ghr command full details can be found on GitHub, however, we really only need to learn one subcommand:

ghr -t ${GITHUB_TOKEN} -u ${CIRCLE_PROJECT_USERNAME} -r ${CIRCLE_PROJECT_REPONAME} -c ${CIRCLE_SHA1} -delete ${VERSION} ./artifacts/

This command uploads specific artifacts, typically binaries, to our GitHub release on GitHub. Let's break this down:

ghr -t ${GITHUB_TOKEN} - Here we start the command and pass it a GitHub token for authentication. This is a GitHub Personal Access Token and not an OAuth token/key.

Specifically created via your personal GitHub account, you'll want to safeguard this token and only load it into the CircleCI environment via a private environment variable.

-u ${CIRCLE_PROJECT_USERNAME} -r ${CIRCLE_PROJECT_REPONAME} - This is where we pass the GitHub user/org name and the repository name. Both values are passed via built-in CircleCI Environment Variables. No extra work is needed.
-c ${CIRCLE_SHA1} - Here we provide the Git commit hash (available in CircleCI as $CIRCLE_SHA1) to ghr. This tells it which commit, and thus tag, the release is for.
-delete - This deletes the git tag and release if it already exists.
${VERSION} - We set the git tag/release version via a $VERSION environment variable. This can be any variable you want or a string. Typically this is the same as the version of your software release.
./artifacts/ - Then we set the PATH to find the artifacts. In this case, everything in a directory called artifacts inside the current directory.

Plain CircleCI 2.0 example

We've walked through how to use ghr to create a GitHub Release but let's see how it can look inside of a CircleCI 2.0 configuration file:

  publish-github-release:
    docker:
      - image: circleci/golang:1.8
    steps:
      - attach_workspace:
          at: ./artifacts
      - run:
          name: "Publish Release on GitHub"
          command: |
            go get github.com/tcnksm/ghr
            VERSION=$(my-binary --version)
            ghr -t ${GITHUB_TOKEN} -u ${CIRCLE_PROJECT_USERNAME} -r ${CIRCLE_PROJECT_REPONAME} -c ${CIRCLE_SHA1} -delete ${VERSION} ./artifacts/

CI Builds CircleCI 2.0 example

This is a CircleCI job called publish-github-release that uses a CircleCI Go convenience image. Here's the breakdown:

Using workspaces, we pull in the binaries for our project from a previous job (not covered in this post).
This job pulls and compiles ghr via go get (since ghr is written in Go).
It populates $VERSION with the output of my-binary --version, our example application for this post.
We then use the ghr command to upload the binaries in the artifacts directory to GitHub.

We can shave a few seconds off of the job above by using the ghr Docker image from CI Builds. It's a lightweight Docker image that already has ghr installed. Here's how the new example config would look:

  publish-github-release:
    docker:
      - image: cibuilds/github:0.10
    steps:
      - attach_workspace:
          at: ./artifacts
      - run:
          name: "Publish Release on GitHub"
          command: |
            VERSION=$(my-binary --version)
            ghr -t ${GITHUB_TOKEN} -u ${CIRCLE_PROJECT_USERNAME} -r ${CIRCLE_PROJECT_REPONAME} -c ${CIRCLE_SHA1} -delete ${VERSION} ./artifacts/

Workflow example

Here's an example of how one of the variations of the above job can be implemented within a Workflow to publish tagged commits to GitHub releases:

workflows:
  version: 2
  main:
    jobs:
      - build:
          filters:
            tags:
              only: /^\d+\.\d+\.\d+$/
      - publish-github-release:
          requires:
            - build
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^\d+\.\d+\.\d+$/

In this example, we have CircleCI kick off the publish-github-release job when a git tag is pushed. How exactly you choose when to publish a GitHub release is up to you, but here we'll do it with a SemVer-like git tag. We say SemVer-like because the tag regex we're using /^\d+\.\d+\.\d+$/ matches tags such as 1.2.3 but doesn't take into account all of the rules of SemVer (Semantic Versioning).

For the sake of completeness, here's what a complete regex for SemVer would look like according to rgxdb.com:

/(?<=^[Vv]|^)(?:(?<major>(?:0|[1-9](?:(?:0|[1-9])+)*))[.](?<minor>(?:0|[1-9](?:(?:0|[1-9])+)*))[.](?<patch>(?:0|[1-9](?:(?:0|[1-9])+)*))(?:-(?<prerelease>(?:(?:(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?|(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?)|(?:0|[1-9](?:(?:0|[1-9])+)*))(?:[.](?:(?:(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?|(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?)|(?:0|[1-9](?:(?:0|[1-9])+)*)))*))?(?:[+](?<build>(?:(?:(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?|(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?)|(?:(?:0|[1-9])+))(?:[.](?:(?:(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?|(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)(?:[A-Za-z]|-)(?:(?:(?:0|[1-9])|(?:[A-Za-z]|-))+)?)|(?:(?:0|[1-9])+)))*))?)$/