DEV Community: Dane Hillard

Choose Boring Releases

Dane Hillard — Thu, 26 Sep 2024 16:52:04 +0000

Academic research increasingly relies on diverse content types, including gray literature and primary source materials, alongside traditional peer-reviewed works. ITHAKA supports this evolving research landscape through initiatives that foster cross-content connections on JSTOR, our digital library that supports research, teaching, and learning. These include infrastructure services that enable institutions to make their digital archives and special collections discoverable on the platform, and a years-long effort to integrate Artstor — a vast collection of images and multimedia for educational use — onto the JSTOR platform.

Albrecht Dürer (German, Nuremberg 1471–1528 Nuremberg). “Alberti Dvreri Pictoris et Architecti Praestantissimi De Vrbibvs…” 1535. Illustrated book, 78 pp.; H: 13 3/4 in. (35 cm). The Metropolitan Museum of Art. https://jstor.org/stable/community.34718827. Just one of the millions of items now available on JSTOR.

On August 1, 2024, the Artstor migration to the JSTOR platform culminated in the need to smoothly guide users from the Artstor Image Workspace (AIW) at library.artstor.org to appropriate counterparts on www.jstor.org. The amount of work this required was daunting; the AIW platform was as large and complex as JSTOR, and covered many different product areas with ownership spread across several different teams. To achieve this transition without drawing focus away from other objectives, we had to adopt a strategic approach.

The challenge

Our two main constituents for this transition were our users — primarily art history researchers and faculty — and search engine web crawlers. Like JSTOR users, many Artstor users start their searches outside of our platforms and need to be able to find things no matter what platform changes we make.

The first piece of the challenge was technical: Client-side routing was used extensively on the AIW platform. That routing wasn’t built with web crawlers in mind, so many modern web crawlers couldn’t handle it very well. Plus, these client-side routes were generally invisible to our servers because they used hash-based routing rather than the history API. Some pages did support server-side rendering so web crawlers could index them, which gave us an additional scenario to support.

The second challenge was human: Domain knowledge about the details of all this routing and the user value of various pages was spread throughout the organization, and the people with the domain knowledge didn’t always have the technical knowledge to deal with the redirects.

Finally, there was the sheer scope of the work to be done. AIW itself was a huge platform, but on top of that we also had to redirect supporting areas like the marketing and support sites. Very early on, we had to set some parameters to rein in the scope:

We wouldn’t guarantee or aim for 100% of traffic to be redirected. Some pages and requests simply couldn’t be redirected anywhere reasonable, and redirecting to generic informational pages can lead to search engine ranking penalties. More importantly for our user focus, it would be disorienting to click a bookmark or a search engine result and get redirected to something irrelevant.
We would create a central, extensible service designed for loose coupling of the URL patterns to match and the behavior when such a match occurred. This would reduce unnecessary coupling and dependencies between teams as well as the context those teams had to hold onto during the migration project.
We would enable teams to implement redirects for the broadest-used page types (such as individual items), but would equally enable implementing redirects for the long tail of irregular page types. This would create a familiar implementation pattern for teams that they wouldn’t have to abandon for more exotic use cases.
We would enable visibility into the behavior of the system as early as possible, so that we could observe the trend over time. This fostered an experimentation mindset: We could develop hypotheses about how the traffic would be handled, implement a change, and quickly confirm or disconfirm the desired effect after deploying the new change. This also gave us opportunities to leverage parts of our deployment platform we hadn’t exercised much previously, adding some greenfield work to an otherwise brownfield kind of activity.

So instead of perfection, we defined our scope as removing as much risk as possible and building in as much confidence as we could ahead of our launch date. Our goal was to coast through the finish line instead of scrambling.

The approach

So how did we do that? A few key tactics showed up for us and made things possible throughout this project.

Practice product-minded engineering

We approached the project using product-minded engineering principles, which leverage user-focused agile techniques and strong cross-disciplinary and interdisciplinary skills to identify problems worth solving. By considering both user needs and architectural needs together, we came away with a more globally maximum solution without oversimplifying or overengineering.

Use traffic shadowing

Traffic shadowing allows inbound requests to be sent to two or more destinations, each able to take some action. Although one system is still responsible for sending a response back to the user, other systems can also make observations about or take action on requests. Our Capstan platform made this easy to try, and it worked very well. We continued serving AIW pages to users while also sending requests to our new redirect service, so we could see how it would behave and perform.

Measure early and often

We built metrics into the redirect service so that as we started implementing and deploying redirect behaviors we could assess the total traffic volume and understand what portion of that traffic was being handled by a known redirect. That was a huge confidence builder, as we could actually demonstrate not only that the service should redirect the implemented URLs once turned on, but that it was in fact doing so — with the shadow traffic.

Use feature flags

Where we couldn’t implement traffic shadowing for some supporting pages, we used feature flagging. With feature flags, we can ship two different behaviors and then allow staff and automated tests to toggle those behaviors on or off before exposing that new behavior to users. Even under normal circumstances we have many teams developing across many areas of the platform, and a feature flagging strategy brings speed and safety by ensuring we don’t have to perform a “big bang” release at the very end of a project.

Think in transition architectures

In effect, all of the redirect architecture we built to support this migration was a transition architecture. But we also built some smaller transition systems to move the control of traffic from external vendors into our own platform, making it easier to flip a switch on release day instead of having to handle several moving parts in a row.

Easing the transition architecture burden made a big difference on several of our support sites. For example, the DNS records for these sites were initially pointed directly at third-party vendors; before we could control the traffic, the traffic would have to come to us. If we waited until release day for that to happen, the DNS change could take longer than expected to propagate, or it could result in unforeseen consequences, or the logic we implemented for it could be wrong. Instead, we designed these constraints away. We worked to bring the DNS under our control earlier, and although it initially continued to point to the third-party vendors, we could now make immediate changes to its behavior.

Create a loosely coupled design

Because we had to collect and implement so much widely scattered domain knowledge into these redirects, we had to build a system that made it easy to contribute and hard to cross wires or step on other people’s toes. The system we created allowed teams to come in with nothing more than a URL pattern to match on AIW and a destination URL to send the traffic to. If necessary, they could also contact downstream services for data to help them decide where to redirect that traffic.

Basically, we decided to meet teams where they are, with their domain knowledge, so they didn’t have to think too much about the technical aspects of how redirection works. This also allowed the team working on the redirect service to do that work without having to worry too much about the domain knowledge. This separated responsibility in a nice way and ensured better outcomes for us and our users.

Have regular, valuable trade-off discussions

Finally, we engaged throughout this whole project in high-quality trade-off discussions. We talked about the level of effort a particular change required compared to the expected user impact. We talked about specific pages and how to handle them. And because we had such a rich cross-section of technical and domain knowledge in those discussions, we made better decisions about how to simplify things or adjust to reduce our overall risk and costs.

This is really a reprise of product-minded engineering, but this highlights one of its most impactful outcomes — giving us context about what’s possible, what gives us the best ROI, and how we might deliver better outcomes for us and users.

The result

We worked hard leading up to our launch date, August 1. But release day itself was one of the most boring of all time. We did about 30 minutes of real work to flip on some of those feature flags and deploy a couple of applications, all of which we were highly confident in because of our previous metrics and testing. In that short time we started redirecting over 95% of all AIW traffic to known locations on JSTOR and its supporting sites. The remaining requests were for things we had intentionally decided not to handle.

We only shipped one bug that we know of, which we spotted quickly. Because of our system design we were able to revert immediately to the old system while we worked on a short-term fix, and within a couple of weeks put a long-term fix in place so we could sunset the old system.

Meanwhile, we’re listening for user experience feedback in case anyone is confused or notices broken redirects, and we’re watching how our search engine crawling and ranking responds. As Google and Bing and others recrawl our content, they’ll start sending people directly to JSTOR. NISO recommends leaving these redirects in place for at least a year, so we’ve committed to that. Next year we’ll evaluate whether this architecture has run its course and act accordingly.

The takeaways

While the technical tools and architecture we used were obviously important, adopting a loosely coupled, extensible design was key to our success. By bringing solutions to teams that allowed them to focus on their domain knowledge we played to everyone’s strengths. It also ensured teams weren’t colliding with each other too often. This approach helped us focus and synthesize everyone’s strengths. It may not be possible in all cases, but for this project it was one of our best and most productive decisions.

By thinking in transition architectures and building key visibility into the system at the outset, we were able to create significant confidence in our progress and readiness for release day, making the finale just a blip on the radar. This raised an unexpected consequence — it would have been easy to say, “Look, we did the thing,” and part ways on release day, because it was so uneventful. Choose boring releases, but be sure to keep the afterparty exciting.

Interested in learning more about working at ITHAKA? Contact recruiting to learn more about ITHAKA tech jobs.

I'm writing Publishing Python Packages

Dane Hillard — Sun, 14 Nov 2021 01:37:35 +0000

This is my first DEV post in quite a while. I've been really busy. In 2020 in the midst of the pandemic we purchased a home across the state, renovated it, and moved. Not long after getting settled into that, I jumped into writing another book.

Over the last several years at ITHAKA I've focused on creating modular code shared across our department and platform, maintaining a few dozen Python and JavaScript packages. I've also come to love the open source community—though I don't contribute nearly as often as I'd like—and thinking about ways to solve some the issues project maintainers face in their day-to-day work.

I hope that my new book, Publishing Python Packages, can make even a small impact in helping project maintainers be more productive through tooling and automation, so they can continue focusing on their projects and communities.

Manning has made a 50% discount code for the book available, and if you've been thinking about grabbing a copy or know someone who might benefit from it, I hope you'll be able to take advantage of this price reduction while it's in early access. Use the code mlhillard350 at checkout.

I'm happy to answer any questions I can about the book, the publishing process, or my writing workflow as well! Hope to hear from you ☺️

Practices of the Python Pro out now!

Dane Hillard — Sat, 11 Jan 2020 17:02:05 +0000

Nearly a year ago I announced that I was writing a book about writing Python code.

I'm writing Practices of the Python Pro

Dane Hillard ・ Jan 31 '19 ・ 2 min read

#python #discuss #beginners #showdev

Practices of the Python Pro is now available! Holding the physical copy in my hand for the first time was a wild experience. It didn't quite become real until that moment.

I set out to fill what I saw as a learning gap for many people entering the software development space today. Some of my friends were either self-taught programmers who owned their own businesses, trying to pick up programming for use with their existing career, or trying to switch careers into software. The diversity of ways people are getting into and using software is growing so fast!

Even as someone with a traditional path into software development, I didn't learn many of the principles in school that lead to more maintainable code. Learning how to separate concerns, use composition over inheritance, and create more extensible code with approaches like plugin-based architecture all happened "in the field" for me. For those with even less exposure to this stuff, it can be hard to even know these options are out there.

Practices of the Python Pro seeks to give an introduction to many of these principles, building a small project that takes advantage of them along the way. My hope is that it demonstrates the values of maintainable code enough to excite you to keep researching and learning more on your own for years to come.

I learned a lot myself in writing this book. Taking what I already knew theoretically and forcing myself to apply it practically to teach others about it was a great way to find gaps in my own knowledge and realize my inexperience in some areas. I think that's the value of writing and the value of platforms like DEV where people can safely explore and discuss ideas with others. Thanks to all of you for such a lovely space in this corner of the web!

Practices of the Python Pro is on Product Hunt

Dane Hillard — Mon, 28 Oct 2019 18:16:57 +0000

A while ago I shared about the book I was writing on software development in Python, and received such a great outpouring of support from the DEV community! Thank you all 💖

I'm writing Practices of the Python Pro

Dane Hillard ・ Jan 31 '19

#python #discuss #beginners #showdev

Today, with the book nearing the finish line in production and with all content available in the early access version, I launched the book on Product Hunt! If you have the time and interest to join the discussion, leave a review (if you've read the book), or share the link around, please do! It would mean the world to me.

My availability to write online or do things for fun has been a bit stagnant for some time, but I hope that I'll be able to start getting back to it soon with a few things coming to a close. I look forward to seeing you all again in no time!

Learn the Django User Authentication System

Dane Hillard — Wed, 07 Aug 2019 15:46:20 +0000

Introduction

Giving users the ability to create an account they can sign into is a common function for many websites.

Users might need an account to participate in a comment thread, save their personal information, or transfer money. Whatever the use case may be, you need to build an authentication system that’s simple and safe for your users.

After reading this post, you should have a solid understanding of how Django thinks about authentication – from users, to groups, to permissions. You’ll also see how Django plays things safe where it can in order to help you avoid inadvertently contributing your users’ information to "Have I Been Pwned".

Users

For most websites, the basic entity of authentication is a user. A user is identified by some unique string, which is almost always an email address or username.

To prove someone is who they say they are, they must provide a password when creating an account, and again at any time they want to authenticate themselves. This should be familiar: you go through this kind of workflow any time you sign up for a service like Twitter or Netflix.

Django provides a User model for creating and managing users. Django users have a username and password, but can also optionally have an email address and a first and last name:

from django.contrib.auth.models import User


rafaela = User('rafaela', password='$uper$ecretpassword')

# OR

rafaela = User(
    'Rafaela',
    email='[email protected]',
    password='$upser$ecretpassword',
    first_name='Rafaela',
    last_name='Lòpez',
)

If you prefer to identify users by their email addresses, I recommend filling the username with the email address and keeping the address in the email field as well. This will allow users to authenticate using their email address while also allowing you to continue using Django’s built-in features that deal with email.

Django provides a level of security when it comes to passwords. It has a built-in set of password validators, some of which are enabled by default in new projects. You can write your own validators to enforce any password rules you might need, but choose wisely – it’s been shown that many password rules lead to decreased security!

In addition to password validation, Django safely stores password information by default. Django salts and hashes passwords before storing them when a user is created, so their plaintext password is no longer available outside the context of the initial registration request or when they log in.

Storing passwords in plaintext is a surprisingly common oversight in the industry, so let Django be your safety rail here!

Like other models you may have used in Django, user objects can be queried and filtered and so on:

User.objects.filter(first_name='Rafaela')

User objects have several other fields, attributes, and methods that will make sense in context as you read on about the Django features that involve users.

Read more about groups, permissions, and more in the full article!

Our Open Source Software in the Wild

Dane Hillard — Fri, 21 Jun 2019 17:20:42 +0000

ITHAKA has a mission to make knowledge widely available, accessible, and sustainable. This mission runs parallel to the open source approach to software development. In making software, systems, and methodologies public, organizations enable others to build on their successes as well as critically examine these artifacts for bugs or security flaws.

The collaborative nature that open source strives toward acts as a tide that raises all ships; the community can produce improvements that benefit everyone. These software changes are tracked over time and the historical record that arises also acts as an audit trail for reproducibility or as a catalyst for someone hoping to learn how something is done.

Our front-end developers that work on JSTOR consume data from a myriad of back-end systems, from those we manage in-house for authentication and search to third-party APIs for fetching data from Wikipedia. As the list of services we interact with grew over the last few years, we found it difficult to manage the services, let alone all the endpoints we communicate with in each of them. We built a Python project, ithaka/apiron, in order to ease this burden. Sometime soon after that, we decided that apiron might be useful enough to others to warrant publication and got to work on all the legal and marketing threads involved.

Since open sourcing apiron, it’s seen moderate but intriguing interest from the Python community. Jeff Triplett, a Director of the Python Software Foundation, was the first third-party contributor to the apiron project. Jeff lives in Lawrence, KS, the birthplace of the Django web framework that we make heavy use of on JSTOR. He organizes the DjangoCon US conference as the president and co-founder of the Django Events Foundation North America.

Another third-party contributor, who we know only by the cryptic handle teffalump, used apiron to build a Python package for communicating with servers managing DICOM, a standard for working with medical imaging records. Excitingly, their work went on to be used by folks in the Brown University Behavioral and Neuroimaging team.

One beautiful consequence of the freedom of open source software is that you never quite know where it will end up. We built apiron to improve how we talk to a search service, and already it’s spread to use cases we couldn’t have imagined at the outset if we’d tried. Exploring these use cases as opportunities to learn will ultimately help us improve our software and ourselves.

As ITHAKA publishes software that generates reach and impact, those we engage with may develop an interest in working with us more directly, perhaps as collaborators or even as employees It’s also a new way to pursue our mission to expand access to knowledge (in all its forms).

If you’re curious about the steps involved in open sourcing projects, my experience with it, how to effectively manage an open source project, or are thinking about using apiron, please leave a comment or reach out to me on Twitter at @easyaspython!

Form habits by making the right thing easiest

Dane Hillard — Thu, 25 Apr 2019 19:09:10 +0000

I'm a creature of habit. I tend to configure things the way I like them, lock that in, and hunker down into the little ecosystem I've made for myself forevermore. When something arises and begins causing friction, my only hope of adapting effectively is to find a new configuration that I can quickly cut over to.

For some time, I've made git commits using a command you're probably used to seeing:

$ git commit --all --message 'Make the code less wonky'

This works alright, but I had this undercurrent of unease about it for the last while. git allows you to specify longer descriptions by formatting your messages a certain way. When you push that commit to tools like GitHub or GitLab and open a pull request, they'll use the short description as the title and the longer description will get plugged into the pull request's description field. Providing this is a matter of strategically adding some newlines to your commit messages, but I often found myself accidentally closing the quotes on the first line of the message or just plain forgetting to provide the long-form description. This was friction.

$ git commit --all --message 'Make the code less wonky

* Fix a bug
* Add some comments
* Remove bitcoin mining malware'

GitHub also recently added a feature for making commits "on behalf of" an organization — useful if you contribute to open source as part of your day-to-day work at your company. Part of this feature involves adding even more information to the commit, with more newlines to remember:

$ git commit --all --message 'Add a bit of wonk back in

* We want those bitcoins so add the malware back
* That "bug" was a "feature" it turns out


on-behalf-of: @some-org <[email protected]>'

This gets pretty unruly, especially if you're trying to commit early and often (something you should do!). I really wanted to start making more descriptive commits, and wanted to have the proper attribution in open source, but this is a lot of friction. Fortunately, git provided a solution that allowed me to adapt.

You can configure git to use a template for your commits, which can be stored in a file. When you don't provide a --message argument at the command line, git will open a text editor where you can edit the commit message, pre-populated with the content of your template. I figured this could be a great way to simplify some of my workflow and prompt me to add more descriptive content to my commits. This automatic prompting is small effort but adds a bit of productivity and improves the information I communicate to others, so it's a big win.

I started by creating the template that fit the commit format to which I aspired:

Summary of change

Longer description of change


on-behalf-of: @some-org <[email protected]>

And then I told git to use it for the repositories I was interested in:

$ git config commit.template /path/to/commit.template

That's about it in terms of setup! But I was able to start reaping its benefits immediately; my command to invoke the commit process is shorter without the --message flag (and the message that follows), and the process of thinking about what to say about the commit is now separate, which gives me a chance to pause and think of something more valuable to say than just haaaaaands.

In case I'm feeling lazy or forgetful, the template also has my back and reminds me that adding context is good to do. It also always has the on-behalf-of commit trailer, so I barely need to think about it. Overall this has saved me a lot of cumulative time, and has made me more thoughtful about what I'm sharing and putting out there. Even on repositories where I don't have this configured (because the configuration has different requirements and I haven't gotten around to it yet), I've at least switched to always using a text editor to edit my commit messages.

So the moral of this story isn't about git. Making the "right" thing the easiest possible option is the way I can truly form habits. If you're like me, if two things are equally easy I'll flip flop on them until I drive myself up the wall, and if the "wrong" thing is easiest I'm doomed. So go out there and squeeze some productivity out of your tooling by making it work for you!

What are your best tool configuration or productivity wins?

A flexible approach to Python API client development

Dane Hillard — Fri, 12 Apr 2019 01:13:05 +0000

Are you working in a microservice-oriented architecture? Is there an API you want to use that doesn't have a Python SDK? Although high-level HTTP libraries like requests aid development by reducing the work you need to do to get up and running, they don't provide much structure around APIs specifically. This can lead to several pieces of similar calling code peppered throughout your system, in the worst cases leading to divergent approaches.

Let's take a look at what a set of API calls could look like using requests. I'll use the PokéAPI, a fantastic (and free!) API for querying Pokémon metadata. The most useful endpoint is /pokemon/:pokemon, which is the main entrypoint for getting information about a particular Pokémon. You can call this endpoint using requests:

>>> import requests
>>> ditto = requests.get('https://pokeapi.co/api/v2/pokemon/ditto')

This returns a bevy of information, much of which links to other endpoints. To inspect the data more easily, you'll want to get the returned JSON as a Python dictionary:

>>> ditto = requests.get('https://pokeapi.co/api/v2/pokemon/ditto').json()

You can verify you've received a response about Ditto by checking its name:

>>> ditto['name']
'ditto'

You can also see that Ditto has one move, named "transform":

>>> ditto['moves'][0]['move']['name']
'transform'

You can also get the endpoint for learning more about the transform move:

>>> ditto['moves'][0]['move']['url']
'https://pokeapi.co/api/v2/move/144/'

You can then call the /move/:move_id endpoint using requests to get its info. That will lead to another response which links to yet further endpoints. There are so many endpoints! They're all under the same PokéAPI umbrella, but there's not much structure in the code which reflects this fact. If some of these endpoints return a single string value instead of JSON, the code to interact with the data will need to change as well. Is there a better way to keep this all straight?

At scale, it's important to understand all the APIs and endpoints your code is calling, in part so that you don't spend effort creating code that duplicates existing functionality. It also makes it easier to survey usage to understand if you've migrated fully away from a deprecated API or endpoint. To do this you need a single source of truth for an API and its endpoints, and ideally a homogeneous way of interacting with them.

apiron is a Python package that addresses these desires by providing a declarative approach that produces SDK-like interaction for you to use. Through introspection of your declared configuration, apiron allows you to start talking to an API quickly and leads you toward a centralized configuration for all of your API dependencies. Let's look at how you might set up the PokéAPI using apiron.

ithaka / apiron

🍳 apiron is a Python package that helps you cook a tasty client for RESTful APIs. Just don't wash it with SOAP.

apiron

apiron helps you cook a tasty client for RESTful APIs. Just don't wash it with SOAP.

Gathering data from multiple services has become a ubiquitous task for web application developers The complexity can grow quickly calling an API endpoint with multiple parameter sets, calling multiple API endpoints, calling multiple endpoints in multiple APIs. While the business logic can get hairy, the code to interact with those APIs doesn't have to.

apiron provides declarative, structured configuration of services and endpoints with a unified interface for interacting with them.

Defining a service

A service definition requires a domain and one or more endpoints with which to interact:

from apiron import JsonEndpoint, Service

class GitHub(Service):
    domain = 'https://api.github.com'
    user = JsonEndpoint(path='/users/{username}')
    repo = JsonEndpoint(path='/repos/{org}/{repo}')

Interacting with a service

Once your service definition is in place, you can interact…

View on GitHub

With apiron you can define a Service, which has a domain and a collection of Endpoints. The Pokémon and move endpoints happen to return JSON, so using a JsonEndpoint will end up returning the response as a dictionary by default. Each endpoint has placeholders that can be filled in dynamically:

from apiron import Service, JsonEndpoint


class PokeAPI(Service):
    domain = 'https://pokeapi.co'

    pokemon = JsonEndpoint(path='/api/v2/pokemon/{pokemon}')
    move = JsonEndpoint(path='/api/v2/move/{move_id}')

This is all fine, but how do you interact with it? apiron provides SDK-like interaction for calling your configured service. That is, apiron tries to feel like something purpose-built for the API you need to use while being flexible enough to do this for any number of APIs. Here's how to make the call to get Ditto's information and information about the transform move:

ditto = PokeAPI.pokemon(path_kwargs={'pokemon': 'ditto'})
transform = PokeAPI.move(path_kwargs={'move_id': 144})

From this code, it's easier to see that you're calling the PokéAPI and using the Pokémon and move endpoints. It's also easier to see what data is being plugged into the calls. If you're using an IDE, you can also jump to those endpoint definitions to see that they return JSON, so you get an idea of what to expect when using the responses. As you look through the PokeAPI class, you can also see which endpoints are already implemented at a glance, and quickly add any that aren't available yet if you know the right path and returned data type.

If the PokéAPI moves to a new domain, or if an endpoint's path changes, there's one clear place to react to that change. You can also call an endpoint with different headers, cookies, and more without having to duplicate much boilerplate. The readability and inspectability of this approach have improved my experience dealing with numerous services with numerous endpoints. In addition to helping users develop clients for APIs they want to use, this package can potentially reduce the effort needed for API providers to give their consumers a Python SDK. I really hope you'll try it out and tell me all the ways you can think of to break it!

Truly taking time off: A checklist

Dane Hillard — Sun, 03 Mar 2019 18:48:08 +0000

This post originally appeared on dane.engineering

I recently returned from nearly two weeks off from my typical day-to-day work. Part of this time was to attend a conference (PyCaribbean was amazing!) and the rest was a legitimate vacation. In the past I've had trouble really disconnecting and enjoying my time away, so this time I took deliberate measures to make sure I didn't fall into the same trap again.

Empty your brain

My time away coincided with a pretty busy time for my team, leading up to a deadline. This can be one of the more difficult times to step away. Paramount to your team's success and your ease of mind while you're gone is making sure everything you have in your head gets out. Disseminate everything you know or have in progress so that there's shared understanding. Ideally, pair with a coworker leading up to your vacation to transition anything that needs to keep rolling while you're gone.

Make agreements as a team about what's expected of you before you leave so that you can commit to getting those things done. It will not only help the team feel harmonized, but will give you a clear stopping point that will mentally let you switch to vacation mode.

Escape from Slack

Slack can be far and away the biggest source of distraction any time you're taking some time to yourself. This is especially true if you use it on your mobile devices. If you only do one thing after syncing up with your team, it should be this.

Slack statuses can be set until a specific date and time, or indefinitely. Set a status with an emoji indicating you're away/on vacation/unavailable, indicating when you'll be back if possible.

In addition to a status, Slack lets you explicitly set yourself to "Away." This makes it more clear in the interface that you're not around, so it helps manage expectations!

I chose the nuclear option on this trip and signed myself out of Slack completely. In addition to removing the occasional distracting notification, it made me less likely to check Slack on impulse during down time.

Escape from email

In a similar vein to Slack, email is one of those things a lot of us check "just in case." There is rarely anything compelling in your inbox, at least nothing that can't wait until you're back. Just make sure there's a protocol for true emergencies, like a personal phone number or email. Ideally these are behind some sort of "BREAK IN CASE OF EMERGENCY" glass. Set an auto-reply message similar to your Slack status, but in addition include the names or contact information of people to contact in your stead. This helps folks get their questions and concerns addressed more quickly.

Escape from your calendar

Calendar reminders are another source of distraction, and one I only realized when I was preparing for this trip. Calendars are also handy for trip planning and organizing, so if there are still recurring work meetings floating around they can cause clutter.

Decline meetings that fall under the time you'll be gone. If they're recurring, make sure you only decline the instance instead of the series! Declining meetings reminds people you won't be attending, which helps them plan their agendas while you're out.

Escape from the pager

If you're on rotation for your team's application monitoring, make sure that you're not scheduled during the time you're out. Swap with someone if you are (and show your appreciation). If unattended alerts get escalated to everyone, you can consider removing yourself from the escalation policy temporarily as well. I didn't think of that beforehand, so I was still caught by a few escalated alerts.

It's about balance

I mentioned that in the past I've had a hard time disconnecting. Part of this is because I personally don't mind being mildly available even when I'm out. This is the balance I'm comfortable with. For others, the balance falls elsewhere, further toward some end of the spectrum. The tips above fall at the "unavailable" end of the spectrum, so you can draw on the bits and pieces you need to strike the right balance for yourself. Be healthy and be well!

What are your tips for unplugging and enjoying time away?

Integrating ButterCMS in your Vue application

Dane Hillard — Tue, 05 Feb 2019 22:52:42 +0000

This post originally appeared on dane.engineering.

Although sites like Medium provide audience reach and a consistent experience, the list of reasons I'm no longer happy with it keeps growing. I've done most of my recent writing here on dev.to, which has been a refreshing change!

I decided to take my maiden voyage into headless CMS, and I've chosen ButterCMS for the moment. Its small but focused API was plenty for me to get my blog up and running! Best of all, it's free for non-commercial use.

Right after you sign up with Butter, you'll get an API key and links to an impressive array of framework-specific instructions for how to get set up. I found the instructions for Vue very easy to follow, and was able to go from signing up to retrieving the test blog post within 15 minutes or so! I'm using single-file components (SFCs) in my app, so I started by grabbing a list of blog posts and creating the template together. Butter returns a data property that contains the list of posts, each of which has a title, slug, body, and so on. We can fetch these when the BlogPostList component is created, so that the data becomes available around the time it mounts. I also put in a loading state for the rare occasion where the API response takes a noticeable amount of time:

<template>
  <main>
    <h1>Posts</h1>
    <span v-if="loading">Loading...</span>
    <ul v-else-if="posts.data.length">
      <li v-for="post in posts.data" :key="post.slug">
        <router-link :to="{ name: 'post', params: { slug: post.slug } }">
          {{ post.title }}
        </router-link>
      </li>
    </ul>
  </main>
</template>

<script>
import Butter from 'buttercms'

const butter = Butter('YOUR API KEY')

export default {
  name: 'BlogPostList',
  data () {
    return {
      loading: true,
      posts: {},
    }
  },
  methods: {
    fetchPosts () {
      butter.post.list({ page: 1, pageSize: 10 })
        .then((response) => {
          this.loading = false
          this.posts = response.data
        }).catch((response) => {
          console.log(response)
        })
    },
  },
  created () {
    this.fetchPosts()
  },
}
</script>

The code for displaying a single post is much the same—a data property contains information about the post and we can fetch the post as the component is created:

<template>
  <main>
    <article v-if="post.data">
      <h1>{{ post.data.title }}</h1>
      <span class="metadata">{{ publishedDate }}</span>
      <div v-html="post.data.body" />
    </article>
  </main>
</template>

<script>
import Butter from 'buttercms'

const butter = Butter('YOUR API KEY')

export default {
  name: 'BlogPost',
  data () {
    return {
      loading: true,
      post: {},
    }
  },
  methods: {
    fetchPost () {
      butter.post.retrieve(this.$route.params.slug)
        .then((response) => {
          this.loading = false
          this.post = response.data
        }).catch((response) => {
          console.log(response)
        })
    },
  },
  created () {
    this.fetchPost()
  },
}
</script>

This is about all you need in order to start fetching a list of posts and rendering each post! The rest of the work is in dropping all the SEO into place (I use vue-meta for this) and styling the content as you wish. One additional thing I did to make using Butter easier throughout my Vue app was adding it to the Vue prototype:

import Butter from 'buttercms'

const butter = Butter('YOUR API KEY')
Vue.prototype.$butter = butter

Then I can just type this.$butter in a component's methods instead of initializing the API client each time.

The features I like about butter so far are:

The easy-to-use API and corresponding JavaScript client
The small amount of time it took to get started
The image API they provide (through Filestack)

The features that could use some work are:

Adding code blocks to your posts: it's way nicer than Medium, but not as good an experience in the WYSIWYG as other more basic things
Terminology: this isn't unique to Butter; a CMS can be complex so it's difficult to distinguish all the concepts you can configure, create, and customize

I'm writing Practices of the Python Pro

Dane Hillard — Thu, 31 Jan 2019 01:48:25 +0000

I'm doing a thing.

I'm pretty stoked to announce that the book I've been working on for the past few months, Practices of the Python Pro, is now available for early access! The first chapter is available for free, and the first three chapters are currently available if you choose to order the book! I'm able to offer everyone 50% off until February 7th by using the code mlhillard at checkout (please let me know if you have any issues at all).

I'm brand new to writing books, so even though I'm teaching others it's been a huge learning process for me as well. I've been writing blog posts and documentation for a while now, but taking someone on a journey through any concept from start to finish is an undertaking! It's certainly the most I've had to think about grammar for about a decade 😄

The review and editing process has been paramount in helping me teach better. Turning around the edits on a chapter is often the most difficult part of writing, but it's resulted in what I hope is a great teaching pace. My goal with this book is to make concepts used every day by experienced software developers accessible and exciting to those just entering the field, all in the context of Python. I'm covering things like namespacing, separation of concerns, abstraction, testing, and design patterns. Python's popularity means people come into it from all angles, so the book will be a source for anyone looking to take the next step in their software journey!

If you find you're interested enough in the book to buy it in early access I'm hoping you will help me help others by providing detailed feedback about anything that's confusing, misleading, or missing. The DEV community has been one of the most supportive, inclusive, inquisitive communities I've ever been a part of and I want to produce something that embodies these values!

I'm sure that I will have plenty more to write about the book writing experience as things progress. I'd love to answer any questions you have; whether about the book, the process, or anything else!

Be more productive with shell aliases

Dane Hillard — Sat, 26 Jan 2019 17:02:22 +0000

The most valuable time as a software developer is usually time spent collaborating and thinking. To get as much of that time as possible, reduce the time you spend typing things with your mortal fingers!

Git

Git is a ubiquitous version control system, and becomes more important as many developers begin collaborating on the same code base. If your organization uses Agile development practices, you'll also be creating many branches and updating master a lot.

I use oh-my-zsh's Git plugin which provides an amazing variety of aliases for common (and not-so-common) Git subcommands. A common workflow in git is to:

Check out the master branch
Update your local master branch with the latest changes from the remote
Create a new branch for your changes
Commit your changes with a good commit message
Push your branch to the remote

Without any aliases, this workflow looks like this on the command line:

$ git checkout master
$ git pull origin master
$ git checkout -b my-feature
# Make changes...
$ git add .
$ git commit -am 'Add my feature'
$ git push origin my-feature

This is fine, but sometimes I forget that pesky -b flag when creating a branch and also get annoyed that I need to state which branch I'm pushing when it's almost always the current one.

With the Git plugin aliases, this workflow takes a lot less work:

$ gcm
$ gl origin master
$ gcb my-feature
# Make changes...
$ ga .
$ gcam 'Add my feature'
$ ggpush  # this takes advantage of oh-my-zsh's git_current_branch

Sometimes you need to stash your changes while looking at another branch or doing more complex things in Git:

$ git stash
# Do some stuff and come back
$ git stash pop

But these aliases come in handy:

$ gsta
# Do some stuff and come back
$ gstp

There are a lot of handy aliases, including plenty with the various flags you might use for a particular Git subcommand:

$ gd  # git diff
$ gdca  # git diff --cached
$ gds  # git diff --staged

I love using these, and the shorthand for them is generally intuitable kind of like Vim. I've added a few of my own for command+flag combinations I use commonly, like:

$ goop  # "git oops": git reset --soft HEAD~1
$ gun  # "git unstage": git reset HEAD --

I also checkout and update master then prune cleaned up remote branches so often that I made a single command, upr (for "update repo"), that does this all for me.

Python

I work in Python and Django most days. The ease and length of my aliases in this arena reflect that; the more frequently I run a command, the shorter its alias:

$ python manage.py runserver  # Nope
$ ./manage.py runserver  # Nope
$ run  # There we go

$ pipenv shell  # Nope
$ psh  # Yep

$ pip install -r requirements.txt  # Hmmm
$ prq  # Indeed!

Odds and ends

There are a few general command utilities that I use often enough to slim them down too. The one I use the absolute most is named, which expands to find . -name. Then I just ask for files named "*.py"! I also default grep to using colors and line numbers by aliasing it to grep -n --color=auto. I can use the bare grep by typing \grep on the rare occasions where it's needed.

You can see all of my aliases here.

Conclusion

The point of all this is that you should spend time thinking about what you want to do and as little time as possible doing what you want to do when using the command line or writing code. I'm able to reincorporate all the time I save into more thinking—usually about all the bugs I've introduced 😉