<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by James Pulec on Medium]]></title>
        <description><![CDATA[Stories by James Pulec on Medium]]></description>
        <link>https://medium.com/@jpulec?source=rss-d0c8058de852------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*ocKEXbz67oqnvfYST8JmeQ.jpeg</url>
            <title>Stories by James Pulec on Medium</title>
            <link>https://medium.com/@jpulec?source=rss-d0c8058de852------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 13:01:14 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@jpulec/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Heroku Ought to be Enough for Anybody]]></title>
            <link>https://medium.com/codex/heroku-ought-to-be-enough-for-anybody-3f5860cae7fd?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/3f5860cae7fd</guid>
            <category><![CDATA[heroku]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[tech-debt]]></category>
            <category><![CDATA[devops]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Wed, 12 May 2021 14:22:29 GMT</pubDate>
            <atom:updated>2022-10-22T18:17:47.480Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/504/1*8kb8vJ_d20aqZAwqPUHmtg.jpeg" /></figure><p><strong>UPDATED 2022: Ever since Heroku has removed their free tier and made clear they don’t plan to continue to innvoate on their platform, I can’t recommend it. The points of this article still stand, but if you’re looking for a PaaS, I’d recommend checking out render.com</strong></p><h3>Heroku Ought to be Enough for Anybody</h3><p>There’s a legend in computing history that Bill Gates once said, “640k ought to be enough for anybody” while describing the RAM limit of the IBM PC at a trade show in 1981.</p><p>This quote is often referenced as shortsighted and makes for a perfect snarky Twitter reply. There’s a similarly uncorroborated quote for Thomas Watson, chairman of IBM, stating in 1943, “I believe there’s a world market for maybe 5 computers&quot;.</p><p>People love to throw around these quotes as examples of poor foresight and as a check on one’s humility towards the unbelievable technological changes that happen in short periods of time. Today’s average user would not be able to get anything done with 640k, which is several orders of magnitude fewer than what you’d find in a ‘stock’ laptop (about 8GB of RAM).</p><p>But there may be something to be gleaned from the original quote that supposedly inspired this particular Gates legend. The un-referenced quote, published in <em>InfoWorld</em> in 1985, is as follows:</p><blockquote>“When we set the upper limit of PC-DOS at 640K, we thought nobody would ever need that much memory.”</blockquote><p>A charitable interpretation is that he believed that PC-DOS would be obsolete long before users encountered this limit. In a 1989 interview, Gates even alludes to this interpretation.</p><blockquote>“I have to say that in 1981, making those decisions, I felt like I was providing enough freedom for 10 years. That is, a move from 64k to 640k felt like something that would last a great deal of time.”</blockquote><h3>What the hell does this have to do with Heroku?</h3><p>I often feel this dichotomy of interpretations when I recommend <a href="https://www.heroku.com/">Heroku</a> as a platform to build a business on. Whenever I try to tell someone that Heroku ought to be enough for them, they inevitably direct me to a blog post about a company such as DoorDash. <em>They had to migrate from Heroku and I don’t want to have to go through that.</em></p><p>Just like the charitable interpretation of the Gates misquote, I don’t mean that Heroku will necessarily be enough for a business forever. I mean that it will probably be enough for a good deal of time.</p><p>The fact is, for the vast majority of businesses, Heroku will handle their traffic just fine for a LONG time and the trade-off it provides to a business in the short term is often the right call to make.</p><p>Yes, your business may grow big enough that Heroku no longer makes sense. But it’s likely that when that happens, the trade-off was still the correct one to make, when measured against the effort of performing that ops work yourself.</p><h3>Right Technology, Right Time</h3><p>Most developers make hundreds (or thousands) of tiny decisions every day in the products they build. It’s often something small like how to handle some sort of edge case that wasn’t considered by a Product Manager. Or it’s choosing what fake data to use for testing.</p><p>But there are a few decisions that have incredible ramifications on an entire organization. Choosing language ecosystems. Making 3rd party library selections. Picking a cloud hosting provider. These decisions impact who the company can hire or might add months of unforeseen work. We do our best, but often one of the strongest tools we have is a set of principles for how our engineering organization makes these choices.</p><p>For example, some engineering organizations try to primarily choose <a href="http://boringtechnology.club/">“boring” technology</a>. They might explicitly model out how many “innovation tokens” they’re willing to spend and try to budget accordingly. Some companies may choose to heavily favor open source software, since that may make debugging issues or contributing fixes easier. Having these guiding principles helps the organization make consistent decisions and allows it to more effectively scale.</p><p>Which brings to me a principle I believe in that seems to often get overlooked:</p><blockquote>Make the decision that is correct for the present, even if we KNOW if may be wrong in the future.</blockquote><h4>Technical Debt by Another Name</h4><p>I’ve always appreciated the analogy of “debt” used to describe certain technical choices. Like monetary debt, technical debt can be an invaluable tool, when used responsibly. It can help you get your product to market months earlier, at the cost of paying down the interest later. To be clear, choosing to do sloppy work or creating an endless backlog of cleanup TODOs is NOT tech debt. And even when people can agree on a definition, many still use tech debt irresponsibly.</p><p>Making a technical choice, like hosting on Heroku, building your product in <a href="https://darklang.com/">DarkLang</a>, or using <a href="https://www.meteor.com/">MeteorJS</a> is just more tech debt. It gives you the leverage you need now, at the cost of paying down that debt in the future.</p><p>Just like with monetary debt, the most important thing here is to recognize when the debt is no longer providing the leverage that encouraged you to incur it in the first place. If you lose sight of this, you wind up in that pit of despair so many developers have become familiar with at the various organizations they’ve worked at.</p><p>This perspective seems most often lost on new members to an organization. They may come in and say “Who the hell made these choices? These were terrible decisions.” While it’s certainly true that their outside perspective may provide the clarity needed to recognize that something needs to change, it often underscores a lack of the principle that I outlined. Most of the time, the people before you made the best decisions they could with the information they had at the time. Often, it’s the case that even in hindsight, they made the best decision they could at the time, even though that decision is no longer correct. Think about this the next time you start a new gig somewhere.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3f5860cae7fd" width="1" height="1" alt=""><hr><p><a href="https://medium.com/codex/heroku-ought-to-be-enough-for-anybody-3f5860cae7fd">Heroku Ought to be Enough for Anybody</a> was originally published in <a href="https://medium.com/codex">CodeX</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[On Launching a Side Project (Or: When The Platform Makes Your Idea a Feature)]]></title>
            <link>https://jpulec.medium.com/on-launching-a-side-project-or-when-the-platform-makes-your-idea-a-feature-a335279d0255?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/a335279d0255</guid>
            <category><![CDATA[entrpreneurship]]></category>
            <category><![CDATA[side-project]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Mon, 03 May 2021 14:32:13 GMT</pubDate>
            <atom:updated>2021-05-03T14:32:13.097Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*3QWW2hPPJdVyYgTwuCQRSA.jpeg" /></figure><p><em>This is the final post in a series of my journey to launch a side project in 2020. You can find the previous posts </em><a href="https://medium.com/swlh/on-starting-a-side-project-or-how-to-just-get-started-e6d65cb01a85"><em>here</em></a><em> and </em><a href="https://jpulec.medium.com/on-building-a-side-project-or-why-i-chose-django-and-htmx-for-a-new-project-in-2020-b4fdeeaecb05"><em>here</em></a><em>.</em></p><p>After working to launch <a href="https://www.mergecaravan.com/">MergeCaravan</a>, I finally felt like the product was ready to be released. I had a few things left to do before doing any promotion.</p><p>First, I needed a way to actually charge customers. Stripe’s Checkout product made this super easy and with just a little work I was able to set up support for monthly subscriptions. By leveraging Stripe, I could ignore all sorts of concerns, such as providing a way for customers to cancel. Checkout handles basic billing management so I wouldn’t have to.</p><p>Next, I needed to set up Google Analytics to understand traffic and if the product was resonating with potential users. I used a great product called <a href="https://www.freshpaint.io/">Freshpaint</a> to do this. If you’ve ever used Segment, it’s quite similar. The big difference with Freshpaint is its ‘autotrack’ capability. Basically, it automatically tracks ALL page views, clicks, and input changes. This allows you to retroactively decide which actions might be interesting and then query them later.</p><p>With the proper tools in place, I started posting about MergeCaravan in a couple different places. I don’t have a large LinkedIn or Twitter following but felt that posting in those places first would be a good start. If I could <em>just</em> resonate with any developers I know, or their colleagues, that would be a great start. After that, I put together a post for Product Hunt. I tried to add a little bit of color around the frustrations that drove me to build MergeCaravan and added some more information on the upcoming roadmap.</p><p>And after all that….</p><h3>*Crickets*</h3><p>Although I did get some early web traffic after posting in various places, none of the visitors were converting. Not only were they not becoming paying customers, they weren’t even connecting their GitHub accounts at all.</p><p>Hmm. I looked at my homepage and made some visual tweaks, hoping that maybe I could make the product appear a bit more professional. I also went and corrected a bug that only allowed users to connect MergeCaravan to a GitHub Organization and made it possible to also connect MergeCaravan to a personal GitHub account.</p><p>And then… <strong>a wild customer appeared!</strong></p><p>Someone made it all the way through my sign-up process and entered their credit card details. I had 14 days to convince this user that what MergeCaravan provided was worth $10 a month.</p><p>To do this, I started by tackling some work around reliability. MergeCaravan needed to consistently do its job and it needed to ‘just work’. I moved some synchronous GitHub calls to a job queue and added some automatic retries. Next, I focused on implementing a feature which dealt with a pain I felt: working hours. I wanted to make sure that MergeCaravan only merged PRs during an acceptable window. The last thing I wanted was for a PR to somehow get merged at 4AM.</p><p>Eventually, that user’s 2 week free trial ended and… they converted to a paying customer! 😄</p><p>I was feeling good about the direction of the product and the opportunity in front of me.</p><p>And then a possibly predictable, yet demoralizing thing happened: Github unveiled ‘Auto merging’ of PRs.</p><h3>GitHub’s Universe</h3><p>GitHub’s annual Universe conference happened in December and one of the features they unveiled was the ‘Auto merging’ of PRs.</p><p><strong>*sigh*</strong></p><p>It was a bit discouraging. While MergeCaravan isn’t identical to what was launched, the provided feature probably satisfies users’ needs enough that they wouldn’t need MergeCaravan.</p><p>GitHub’s Auto Merging is an 80% solution. It probably satisfies what most people need. It doesn’t do anything flashy, like preventing merging outside working hours, but it’s integrated in the the Pull Request workflow and makes dealing with PRs a better experience.</p><p>This isn’t the first time GitHub has launched an 80% solution. I had a very similar feeling when GitHub launched GitHub Actions. I think that for 80% of cases, GitHub Actions is easier to set up and has the advantages of being more tightly integrated. It’s what makes me generally bearish on CircleCI as a business in the long term. There’s still 20% of cases for which CircleCI will provide a better experience, especially for specialized requirements that Actions won’t support. But that’s a much smaller market compared to all users who need continuous integration.</p><h4><strong>The Platform Problem</strong></h4><p>I’ve wondered for a while how a platform like GitHub, which has its own marketplace, balances what it builds against what its partners do. For example, when GitHub launched Actions they were beginning to compete directly with other CI platforms like CircleCI and TravisCI, both of whom have been long time partners.</p><p>How do you balance that as a platform? What’s the calculus in their heads? Since I’m not even on the GitHub marketplace, I’m sure MergeCaravan isn’t on anyone’s radar there at all. So it certainly wasn’t a question they were asking themselves as they built this feature.</p><p>More broadly, as a maker, how do you properly assess the risk of building a business on a platform, knowing that one day the platform may try to compete with you and probably do a better job?</p><h3>What Did I Learn</h3><h4>Beware the platform</h4><p>The biggest takeaway from this experience: really assess the risk of building on a platform and understand how that can cripple your business. This story has played out many times before on many platforms and GitHub is no exception. In some cases, they’ve competed directly with platform partners (e.g., CircleCI) and in other cases they’ve gone and acquired their partners (e.g., Dependabot and Pull Pandas). There’s always a risk that a platform might try to make your product a core part of the platform.</p><p>To be clear, GitHub maintains a public roadmap so this wasn’t a complete surprise to me. But it was still disheartening. I knew that for most users, this solution was good enough.</p><h4><strong>I took too long and was embarrassed</strong></h4><p>It’s cliche, especially as an engineer, that I would spend too much time working on perfecting building or cleaning up code and not launch soon enough. I knew this going into it. And I still took too long. In grand total, I made my first commit on May 1st and I didn’t feel comfortable launching until August 31st. That’s 4 months, for a small product. Yet, I kept telling myself things that seemed like they could justify delaying. “This doesn’t handle manual merges.” “This doesn’t support Github’s Organization model.”</p><p>My design skills aren’t the best, so I thought I needed to make some changes and make my homepage prettier.</p><p>The page initially didn’t update automatically, so it had to be manually refreshed for updates. (Oh the horror! 👻)</p><p>There were also things that I took my time with, since I believed they were critical. For example, extensively testing the code that determined what branches to merge and when. I felt that getting this wrong could be catastrophic for a user, so doing it right wasn’t negotiable for an MVP.</p><h4><strong>Getting that first paying customer feels incredible</strong></h4><p>I don’t know if there’s a good set of words to describe how wonderful it is to build something and to have someone want to pay you for it. Even at $10 a month, just knowing that you’ve provided someone a bit of value is incredible.</p><p>I cannot recommend enough getting a customer to pay you for a product you’ve built. Seriously, it’s a hell of a drug.</p><h3><strong>Onward</strong></h3><p>I’m glad I launched a product that I built entirely from scratch, even if only with minimal success. Next time, I’ll know to ship sooner and devote more efforts to promotion. (And maybe I’ll think twice before building on a platform that can cannibalize my product.)</p><p>2020 was a unique and challenging year. And yet I managed to build, launch, and get customers for my product. <em>Just ship it.</em> That’s what I kept telling myself. I waited, and took too long, and dragged my feet to launch and promote, but eventually I did it. I got there. And I take a lot of solace in that fact.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a335279d0255" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[On Building a Side Project (Or: Why I Chose Django and htmx for a New Project in 2020)]]></title>
            <link>https://jpulec.medium.com/on-building-a-side-project-or-why-i-chose-django-and-htmx-for-a-new-project-in-2020-b4fdeeaecb05?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/b4fdeeaecb05</guid>
            <category><![CDATA[django]]></category>
            <category><![CDATA[solopreneur]]></category>
            <category><![CDATA[side-project]]></category>
            <category><![CDATA[htmx]]></category>
            <category><![CDATA[startup]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Sat, 20 Feb 2021 23:50:30 GMT</pubDate>
            <atom:updated>2021-05-03T16:11:52.040Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4rrJfIiUIsweEN_NUbiJ_g.png" /><figcaption>You got your htmx in my Django!</figcaption></figure><p><em>This is the second post about my journey launching a side project in 2020. The first post can be found </em><a href="https://jpulec.medium.com/on-starting-a-side-project-or-how-to-just-get-started-e6d65cb01a85"><em>here</em></a><em> and the last post </em><a href="https://jpulec.medium.com/on-launching-a-side-project-or-when-the-platform-makes-your-idea-a-feature-a335279d0255"><em>here</em></a><em>.</em></p><p>Last year, I set a goal for myself: <em>Build, launch, and close a paying customer for a product that I built entirely on my own. </em>I was working at a startup called <a href="http://resource.io/">Resource</a>, and a daily problem that I encountered was driving me crazy. We had all these PRs on Github that had been reviewed and were ready to merge, but we were left waiting for checks to pass, and constantly hammering Github’s ‘Update Branch’ button.</p><p>Thus <a href="http://mergecaravan.com/">MergeCaravan</a> was born.</p><p>But before I could get started building, I had to figure out what tools and technologies I’d be using.</p><p>I’d been working at Resource for around 2 years, primarily doing development with Javascript, both on the frontend and the backend. We used GraphQL with React and Apollo Client pretty heavily and I’d become quite familiar with both. We’d also started playing around with <a href="https://hasura.io/">Hasura</a>. Before Resource, I worked with Django, DRF and VueJS for 4 years. Knowing that I’d be working alone on MergeCaravan, I decided to optimize my technical choices based on a desire for simplicity. Which led me to confront a gut feeling I’ve had for many years…</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/456/1*pUwS7gsXoXVI7yyalDUCzA.png" /></figure><h3><strong>There’s something terribly wrong with this industry, isn’t there?</strong></h3><p>On numerous occasions during my time at <em>Chewse</em>, I felt like there was something terribly wrong with the direction of modern web development. I couldn’t quite put my finger on it, but so often it felt like I was always fighting the tools and technologies that we were using. Maybe it was because we used Django on our backend, which was initially designed for multi page server rendered apps, but we were using it with Django Rest Framework for an Angular and Vue SPA. Maybe it was the difficulty we had in designing REST resources that made sense and didn’t require us do a lot of roundtrips to get all the data for a page. Maybe it was the level of complexity that went into properly configuring Webpack. (Configuring Webpack v1 was rough)</p><p>Whatever it was, I always had this nagging feeling in the pit of my stomach that there had to be a simpler way.</p><p>One day, I stumbled upon <a href="https://intercoolerjs.org/">Intercooler.js</a>. Where other JS frameworks and libraries pitched owning the frontend completely, Intercooler described itself as enhancements to HTML. It was supposed to supplement your existing web application, rather than try to reinvent a lot of its functionality. I became very interested in the ideas it described, which sent me down the rabbit hole of reading a lot about REST and HATEOAS.</p><p><strong>The Road to HATEOAS</strong></p><p>Ask the average developer about REST, and you’ll likely get some response about resources and using different HTTP verbs for different actions. It’s not an incorrect answer, but it may be a bit of an incomplete one. There’s been a lot written about what Roy Fielding outlines in his initial dissertation on REST and what “RESTful” really means. What often isn’t discussed is HATEOAS, or Hypermedia as the Engine of Application State. I won’t try to explain too much, so go check out the <a href="https://en.wikipedia.org/wiki/HATEOAS">Wikipedia article</a> if you want a deeper dive. But at a high level, it suggests that an application should return both data, and what operations can be performed on that data when sending it over the network. Occasionally, you find this with JSON REST APIs, often encoded with an object in a _links field.</p><p>However, HATEOAS doesn’t have to be implemented as JSON APIs. It can also be implemented using HTML. This is the approach that IntercoolerJS took. Using HTML, Intercooler returns not just the content to show the user but also the actions that can be taken (as form and link tags) encoded in the HTML. It embraces using the returned documents to provide a user the application state as they should be able to interact with it.</p><p>For the first time, that gut feeling I had about the pains of modern web development seemed to ease a bit. It all seemed to click. We could still use the same technologies and tools, and take advantage of native browser features with our apps. We didn’t have to throw away all the advancements we’d made in server side templating.</p><h3><strong>Focusing on simplicity</strong></h3><p>I thought back to my experience with Intercooler when I decided I was going to build MergeCaravan. Knowing that I would be building this project alone, I wanted to address what I knew would be a few concerns right away.</p><p><strong>Managing complexity is of paramount important when you’re a lone developer</strong></p><p>Knowing that I didn’t need to onboard other developers, I decided to work with tools that allowed me to execute as fast as possible. I have a high level of familiarity with Django, so it was an easy call for me to make. However, I was still left asking myself if I should be building a JSON REST API, or just stick with Django’s standard server rendered pages.</p><p>I was reminded of a conversation I had several years ago with a co-worker about the shifting of application logic from the backend to the frontend. Gradually, as applications shifted from being server rendered to being client rendered, more logic found it’s way to the client, which included things like authorization and validation rules. During a conference talk he gave, he presented the following slides highlighting this idea.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-taTT31mCiWCffUUKAQ-Ag.png" /><figcaption>The Old Way</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2PbF7lp2nEAKBhobqguTXw.png" /><figcaption>The New Way</figcaption></figure><p>Intercooler promised to return to the first model, where application logic was wholly handled on the backend, and no longer split with the client. I’d no longer find myself duplicating validation logic in Javascript and on a REST endpoint, or duplicating permission handling client side to determine what UI elements would be visible to a certain user.</p><p><strong>Existing tools just work and provide lots of bang for your buck</strong></p><p>It’s not just my own proficiency that made me opt for a traditional server rendered app. Many existing tools and technologies are still easiest to get started with when using server rendered apps. Spinning up a traditional Django app on Heroku is a breeze. Everything just works and using HTTP caching is as simple as configuring your headers properly. Tools like Sentry require one line to get started, and now you have observability in your app. I appreciate how ‘boring’ and well understood these technologies are.</p><p><strong>I knew up front that I didn’t need high interactivity.</strong></p><p>I’m generally a firm believer in the distinction between web ‘pages’ and web ‘apps’. In this case, I felt that MergeCaravan fell pretty squarely in the ‘page’ category. It doesn’t really make any sense to use offline, since it relies so heavily on Github. It also just doesn’t require a whole lot of user interactivity. There aren’t many places where I need realtime data or where autosaving form data or dragging and dropping make sense. This made it easy for me to avoid large JS libraries and try to just focus on building my app.</p><h3><strong>But what is htmx?</strong></h3><p>When I started building MergeCaravan, I decided to use Intercooler for my frontend needs. Shortly after I began, <a href="https://htmx.org/">htmx</a> launched as the successor to Intercooler. Since I had written little code and was willing to build on a fairly new library, I ported my code over.</p><p>htmx is an absolute breath of fresh air. Getting started is as simple as adding a script tag. No Webpack builds or fiddling around with npm. It’s easy to add to an existing project, and progressively add interactivity as your application needs it.</p><p><strong>Okay. But aren’t multipage apps slower?</strong></p><p>Aren’t single page apps slow? I’ve read endless documentation about improving the performance of single page apps. There’s a lot of different strategies and cool things you can do to help provide better performance for your single page app. And yet the vast majority of SPAs I’ve used generally don’t do these things. It takes a LOT of work to build performant SPAs, and unless your SPA performance directly correlates with a company’s bottom line (i.e. ads or e-commerce), improving performance often isn’t a high priority. It’s very possible you would get better performance for your app by just sending HTML partials over the wire instead of using JSON. HTML actually compresses quite well, and browsers have been optimized to render it very quickly.</p><p><strong>Embrace HTTP</strong></p><p>HTTP has a pretty simple model that’s well supported and well understood. GETs for fetching data. POST, PATCH, DELETE for modifying data. Browsers and caching infrastructure all understand these ideas. Browser security is built on top of this paradigm. You get so much for free by just embracing HTTP methods as they were intended.</p><p><strong>Embrace HATEOAS</strong></p><p>Coupling your UI with your data is a <em>good</em> thing. It simplifies authorization, and handles both concerns in the environment you control: the server. In the same way that it’s a bad move to separate concerns by technology (like separating CSS from HTML), separating your data from your UI is cross cutting concerns the wrong way.</p><p><strong>Acknowledge that Security is Hard</strong></p><p>Security for web apps is hard. So many inherent properties of the web as a platform make it incredibly challenging to get everything right. Whether it’s SQL injection or XSRF exploits, there are a large number of ways to get things wrong. While it’s the case that you definitely need to deal with these issues if your app is a server rendered app, when you choose to go the JSON API or GraphQL route, you end up handling some of these concerns in multiple places. The more you put your business logic in JS client code, the more likely it is that some constraint is encoded there but not in the relevant API code.</p><h3><strong>I’m sold. htmx is perfect, right?</strong></h3><p>Well, not quite. I’m quite happy with htmx, but there are certainly some shortcomings worth mentioning.</p><p><strong>Best practices</strong></p><p>This is probably my biggest complaint. As one might expect, with a younger ecosystem a standard set of best practices has yet to emerge. The htmx website provides a nice set of examples to help you implement some typical web patterns, but it can still be a bit difficult to understand how to split your application. You might find yourself beginning to add some interactivity to an existing page and have a hard time figuring out what parts of them DOM to swap. Should I swap large parts of the tree, or just try to swap the smallest pieces? These questions can be a bit hard to answer at first, and take some trial and error to figure out what works best. It seems that something like a full-fledged tutorial might help new users recognize these patterns sooner.</p><p><strong>URL Organization</strong></p><p>This isn’t exactly a fault of htmx, since it is the responsibility of your server, but I still don’t think I’ve figured out the best way to organize my urls for an app with partials. Using a typical JSON REST API resource url scheme doesn’t quite feel right, since those routes are often good as user facing urls for ‘detail’ pages for a given resource. I’ve also tried appending a string related to the partial’s use case to the resource. For example, a partial related the status of an order would have the path /orders/12345/status. This is best I’ve come up with, but I still suspect there’s a better way. Similar to how there’s a pretty well understood set of conventions for JSON REST APIs, I’d love to see some standardization around how urls get organized for partials.</p><h3><strong>With htmx, the past is the future</strong></h3><p><a href="https://htmx.org/posts/2020-11-24-htmx-1.0.0-is-released/">htmx released version 1.0 not that long ago</a>. In many ways, it takes a lot of the best parts of the web from the past, and updates them for the needs of modern web applications. If you’re also looking to alleviate that weird gut feeling you’ve had around modern web development, or if you’re just looking for a simple way to build web apps, I’d recommend giving it a try, paired with your favorite server-side web app framework, i.e Django, Rails, Laravel, etc.</p><p><em>In the next and final post, I’ll discuss launching MergeCaravan, the aftermath, and what I learned during my journey of launching a side project. Check it out </em><a href="https://jpulec.medium.com/on-launching-a-side-project-or-when-the-platform-makes-your-idea-a-feature-a335279d0255"><em>here</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b4fdeeaecb05" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[On Starting a Side Project (Or: How to Just Get Started…)]]></title>
            <link>https://medium.com/swlh/on-starting-a-side-project-or-how-to-just-get-started-e6d65cb01a85?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/e6d65cb01a85</guid>
            <category><![CDATA[startup]]></category>
            <category><![CDATA[github]]></category>
            <category><![CDATA[side-project]]></category>
            <category><![CDATA[solopreneur]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Mon, 01 Feb 2021 06:09:16 GMT</pubDate>
            <atom:updated>2021-02-20T23:51:37.232Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*5fPFP80AHdtg7Y1X" /><figcaption>Photo by <a href="https://unsplash.com/@tateisimikito?utm_source=medium&amp;utm_medium=referral">Jukan Tateisi</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p><em>This is the first of a few posts about my journey launching a side project in 2020.</em></p><p>At the beginning of 2020, I set out a goal for myself:</p><blockquote>Build, launch, and get a paying customer for a product that I built entirely on my own.</blockquote><p>As much as 2020 was a dumpster fire of a year, I’m thrilled to say that I managed to achieve that goal. In this post, I’ll outline why I set that goal, why I chose to build <a href="https://www.mergecaravan.com/">MergeCaravan</a>, and what I learned about launching a side project.</p><h3>Why Do This?</h3><p>During my professional career, I’ve worked at startups in different phases and in different capacities. When I joined a catering startup called <em>Chewse</em>, I was fresh out of college and was joining the company as the only non-founder engineer, while the company was still pre-series A. An MVP already existed, and the company had a number of paying customers. During my time there, I learned a LOT about software development and what it takes to grow a business. As the company grew and raised more capital, I found myself doing more and more to help scale the business. Whether it was on the technical side, or when I started leading engineering, new sets of problems awaited me.</p><p>After 4 years of growth with the business, I decided to step away, and I knew there were gaps in my skills I wanted to fill. I started looking for companies that were even earlier than <em>Chewse</em> was when I joined and that needed makers. That’s how I found <a href="https://www.resource.io/">Resource</a>.</p><p>When I joined as the 6th employee, I knew there would be a lot of new learning in front of me. However, there were several things that were the same as when I started at <em>Chewse</em>. Resource also already had an MVP and a set of paying customers. Yet, given the nature of the product and the size of the team, I was excited to have more influence on the Product side of things. This all brings me to why I set this goal for myself this year.</p><p>I wanted to expose myself to all aspects of Product Development and to the other aspects of launching a product. I didn’t have much experience in optimizing SEO or marketing products, so I wanted to grow in that area. I’d never found myself in a true sales role, and I wanted to learn how to do that. I’d never found myself having to figure out how to price a product, and I would have to figure that out. I wanted to be thrown into all the problems that come with launching a product yourself.</p><p>Having set this goal for myself, all I needed now was an idea for a product…</p><h3>Why MergeCaravan?</h3><p>I set my initial goal without having any idea of what I would build. I just wanted to stretch beyond my engineer skillset. Knowing this in the back of my mind, I tried to pay attention to when I felt frustration during my day to day.</p><p>Eventually, I noticed something while working at Resource that kept cropping up, related to our code merging strategy. We use a slightly modified <a href="https://guides.github.com/introduction/flow/"><em>github flow</em></a><em>, </em>meaning we use short-lived feature branches and deploy continuously. In order to keep PR reviews manageable, we encourage small PRs and try to get them merged quickly.</p><p>We also use a monorepo, which inevitably means we have some contention for merging code, even with a small team. In order to be as careful as possible, we also require that any code to be merged has the most recent head commit merged into it. Github allows enforcing this for a branch by checking the <em>Require branches to be up to date before merging</em> box under a branch protection rule. By doing this, we ensure that tests are run with exactly what code will be deployed.</p><p>Our test suite takes about 10 minutes to run, so we have to wait about that long between merging each PR. When we have a lot of PRs, this means waiting with that Github PR open in a tab, refreshing until the merge button turns green. God forbid if someone else beats you to it, because then you need to merge master in and start the process all over again. Even with a small team, when you have a process that favors small PRs, and use tooling like <a href="http://com/">dependabot</a>, you can have a large number open quickly.</p><p>After thinking about this a bit, I also realized this wasn’t the first time I’d run into this problem. It was also an issue when I worked at <em>Chewse</em> as an engineer. Of course, when this problem gets bad enough and it takes too long to get code merged, people become incentivized to just ignore the branch protection rule and merge their code, checks be damned.</p><p>I looked at this problem, and recognized that it was a pain I could solve, so I started looking at the Github API docs to see what was available to me. The API allows fetching all the PRs that a given repo had, merging them, checking if they’re valid to merge, and even keeping them up-to-date. It looked like everything I needed was there. All I would need to do was build a service that tracked an ordered queue of PRs that were intended to be merged, keep them up-to-date as needed, and then merge them as soon as a PR was at the top of the queue.</p><p>Thus, the idea for MergeCaravan was born.</p><h3>Getting Started</h3><p>I picked a hell of a year to set this goal. On one hand, working from home full time meant that I was able to better utilize my time, so I should have had enough to commit to a side project. On the other hand, lack of clearly defined boundaries meant that sometimes I was doing the work I wanted to get done for Resource, and the next thing I knew, it was already 10pm.</p><p>Despite also having a larger amount of free time, I often found it challenging to be motivated to work on something else with everything that was going on in the world.</p><p>And to top off all of that, Resource was actually in the process of building an entirely new product. Given that I was already working at a startup which was also in the process of working on a new product launch, I knew I would have to plan my time carefully if I would have any chance of achieving my goal.</p><p>Looking back (and checking my git history) I managed to make my first commits in early May. I finished the initial prototype during one long weekend of development. All it did was listen to Github’s webhooks, and tried to merge code in response to adding a label to a PR. Simple enough. After that, I had to start asking myself what a real MVP would look like. What features were required to launch? Did I need to support different merging strategies, or could I just always use merge commits? What about reordering PRs in the queue?</p><p>I started compiling a list of what I thought was required for an MVP, and began the process of building and launching MergeCaravan.</p><h3>What Did I Learn</h3><h4>Everyone has Daily Pain</h4><p>Everyone you encounter… your coworkers, your significant other, your neighbor have things that irk them everyday. I have these too, although I think I’ve probably done a pretty good job trying to ignore them in my day to day life.</p><p>I’ll admit that I often have difficulty with recognizing these daily pains. I realize it every time I watch someone try to use a new piece of software and see what happens when something doesn’t align with their expectations. When I see these problems with the software I use, I try to imagine what the developer was doing when they wrote this, and use that as a basis for my expectations. In many ways, I think it causes me to be a bit of an apologist for software with poor usability and frankly just causes me to tolerate poor software far more frequently than I should.</p><p>I had to drop that idea and just look around me. What was really grinding my gears? One of the benefits of being a developer, is generally having a good sense about what can easily be automated. What pains were just unacceptable, and I KNEW should be automated with software? This was the area I should focus on, and not let the perspective I have as a developer work against me.</p><h4>Budgeting My Time Was Key</h4><p>Since I was already working a full time job at a startup that was working on a new product, I quickly realized I needed to budget my time better. One of my biggest learnings and changes this year was trying to adopt small habits that I did everyday.</p><p>Still, finding the motivation to work on a side project after spending all day working at a full time job can be really tough. Some days I wouldn’t manage to do anything but make a small copy or design tweak. Other days, I would implement entire features.</p><p>Even a habit as simple as “open the repo issues page everyday” helped to keep me moving forward. Eventually I was able to get to a place where I would work 10–15 hours per week on MergeCaravan, between a few hours on weeknights and more hours on the weekend. If I hadn’t been able to figure this out, there’s no way I ever would have managed to put enough time in.</p><h4>Just Get Started</h4><p>These are the words I just kept telling myself, especially as I first sat down to write code. <em>Just get started</em>.</p><p>I repeated them over and over to myself whenever I had the urge to read more about my chosen technology. When it comes to building, inertia is an incredibly powerful force, and it can take a lot to build it initially.</p><blockquote>This is just a toy. Maybe I should try to find a better idea.</blockquote><p>So what? It’s fun. Just get started.</p><blockquote>You’re no designer. This looks like shit. Maybe I should level-up my design skills first.</blockquote><p>Who cares? Just get started.</p><blockquote>Will anyone even know this exists? Maybe I need to do some reading about SEO.</blockquote><p>Fuck that. Just get started.</p><p>Over and over again, I reminded myself that none of this other stuff mattered. At least not yet. First, I needed to get started. I needed to get something out the door.</p><h3>Now What?</h3><p>All in all, it was a lot of work, but I’m glad I “just got started”. Shipping something I built entirely on my own has been incredibly satisfying, and I learned a lot during the process.</p><p>I learned to more effectively budget my time and most importantly, I had to resist my urge to tolerate the world around me. As Paul Graham mentions:</p><blockquote>“The advantage of taking the status quo for granted is not just that it makes life (locally) more efficient, but also that it makes life more tolerable.”</blockquote><p>That tolerance, while comfortable, is an impediment to seeing opportunities for improvement. Once I was able to consciously cast aside that tolerance, I was able to see the possibility of MergeCaravan. While it is nowhere near complete, I’m happy with what I was able to launch.</p><p><em>You can find my next post about the technical choices I made when developing MergeCaravan </em><a href="https://jpulec.medium.com/on-building-a-side-project-or-why-i-chose-django-and-htmx-for-a-new-project-in-2020-b4fdeeaecb05"><em>here</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e6d65cb01a85" width="1" height="1" alt=""><hr><p><a href="https://medium.com/swlh/on-starting-a-side-project-or-how-to-just-get-started-e6d65cb01a85">On Starting a Side Project (Or: How to Just Get Started…)</a> was originally published in <a href="https://medium.com/swlh">The Startup</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Why You Should (Often) Wrap Your Dependencies]]></title>
            <link>https://levelup.gitconnected.com/why-you-should-often-wrap-your-dependencies-5fced2999616?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/5fced2999616</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Wed, 22 Jul 2020 12:06:01 GMT</pubDate>
            <atom:updated>2020-07-23T00:30:39.396Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*a5IndvIr0RqWgtSO" /><figcaption>A good wrapper hides the tastiest implementation details</figcaption></figure><h3>How Wrapping Your Dependencies Will Save You From Future Suffering</h3><p>A few months back, I was talking with one of the other developers on our team and somehow we got onto the topic of what I thought my biggest learning in the past couple years was at our company. I’d been working as a software developer for the past 6 years and at <a href="http://www.resource.io/">Resource</a> for just over 2 years.</p><p>“Wrap your dependencies,” I told my coworker with the sort of gaunt stare you expect to see from a grizzled war veteran.</p><p>Despite the fact that I’ve been writing software for over half a decade, I didn’t learn this lesson until more recently. Prior to working at Resource, I worked at a company doing full stack work with Vue.js on the frontend and a Django backend. During my time there, I primarily dealt with dependencies from <a href="https://pypi.org/">PyPI</a> and occasionally dealt with the <a href="https://www.npmjs.com/">npm</a> ecosystem for adding a component library or a small utility library. This all changed once I started working at Resource. When I initially joined, the code base was written using MeteorJS. Shortly after I began, we migrated to a React/Node stack. It didn’t take long for me to realize that a lot of what I’d been told by friends and colleagues about the quality of npm packages was true: a lot of packages are just shit.</p><p>Historically I’ve tended to be the sort of developer who has leaned into using existing packages when possible. I have an aversion to reinventing wheels and abhor <a href="https://en.wikipedia.org/wiki/Not_invented_here">NIH</a> syndrome. Yet this attitude definitely caused me some pain once I was working in the npm ecosystem day in and day out.</p><p>After spending far more time coping with this pain than I’m proud to admit, we began to adopt a strategy that would save us a lot of heartache: we decided to start wrapping the third party dependencies in our code.</p><blockquote>Note: I use the word wrapper in this post to describe a group of design patterns that involve adding some abstraction between your code and a third party dependency. People sometimes use words like “adapter” or “facade” to indicate wrapping code with a certain intent. Does this code need to adapt its arguments to interact with some other code, or am I creating a facade in front of this other module to simplify its interface? When I say “wrapper” for the rest of this article, I use it as an all encompassing term which includes these patterns and doesn’t worry too much about intent.</blockquote><h3>The Setup</h3><p>The first time you’ll regret not wrapping your dependencies is probably gonna play out like the following. One day, you need some common functionality that you suspect exists in a third party library. You dutifully search npm until you find a library, such as <a href="https://www.npmjs.com/package/request"><em>request</em></a>, which provides a simple API to make HTTP requests. You add it to your project and don’t really think about it.</p><p>Months or maybe years later, something unthinkable happens; <em>request</em> has become deprecated, with no plans to add any new features and no guarantees that bugfixes or security patches will be merged.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*TAPYWFSYJ6TO1gPXH99Uxw.jpeg" /><figcaption>You after reading your library is being deprecated</figcaption></figure><p>Uh-oh. That’s not good. Guess you better find a replacement for it. You select what seems to be a popular HTTP library, <a href="https://www.npmjs.com/package/cross-fetch"><em>cross-fetch</em></a>.</p><p>Unfortunately, the API for <em>request</em> and <em>cross-fetch</em> is fairly different. <em>Request</em> has convenience methods for each HTTP method, whereas <em>cross-fetch </em>expects a url and a configuration object with a method key. <em>Request</em> takes a json parameter, whereas <em>cross-fetch</em> expects you to call .json() on the response. And so the list goes on.</p><p>If you have good tooling and aren’t doing anything too crazy with your build system, this might not be too difficult of a change. You might start by doing some form of a crude find and replace, and after that start manually inspecting all the places where you previously used <em>request</em>. In a large codebase, this can be a nightmare and can be quite risky.</p><p>This is one of the best reasons to wrap your dependencies: it makes replacing a dependency a much easier task.</p><h4>A Tale of Two Imports</h4><p>Now imagine that when you had first decided you needed an HTTP library, you had instead wrapped the <em>request</em> library with a module of its own. You can envision it looks something like the following.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1083239bd3e731fed42bd36b0ec27be5/href">https://medium.com/media/1083239bd3e731fed42bd36b0ec27be5/href</a></iframe><p>At first, this looks like a fairly useless module. Functionally, it does the same thing, but now instead of writing an import like import request from &#39;request&#39; all over our codebase, you instead write import myRequest from &#39;myrequest.js&#39;.</p><p>Eventually, when that day arrives where you need to replace <em>request</em> with <em>cross-fetch, </em>you now only need to make changes in this one file. You just need to adapt the arguments that the <em>request</em> API takes and transform them into the shape that <em>cross-fetch</em> expects. The following gist shows how this might look.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/67b0bd6ecbfc70516fc06712f8bebd40/href">https://medium.com/media/67b0bd6ecbfc70516fc06712f8bebd40/href</a></iframe><p>It’s definitely a bit painful to write that code. But it’s a lot easier than trying to find all the places in the codebase where you’re making HTTP requests and updating them to conform to the API of <em>cross-fetch</em>. It’s also a lot safer.</p><p>Not only are you now able to replace this dependency when you have to, such as for security reasons, but it also gives you the flexibility to replace it for other reasons. Perhaps you discover that one of these code paths is really critical to your product and is too slow. You go check npm and discover there’s a fetching library that performs better which can be swapped in.</p><p>Or maybe you run into a bug while the maintainer of the library is on vacation. Ideally, you’d fix the bug in the source of the library itself and submit a pull request to the project. But if you need the fix immediately, you can easily patch it at the source inside of your wrapper.</p><p>However, being able to easily replace a third party dependency isn’t the only benefit using a wrapper confers.</p><h4>When Good Tests Go Bad</h4><p>In the scenario without the wrapper, you probably noticed something else while replacing all the call sites to now use the <em>cross-fetch</em> API. You made your changes and then saw a bunch of tests break. This is because a bunch of tests were mocking the <em>request</em> dependency, but are now trying to use <em>cross-fetch</em>. Now you’re stuck updating a bunch of test code, even though you haven’t changed the actual business logic that makes HTTP requests.</p><p>There’s an adage often stated when it comes to testing: Don’t mock what you don’t own. The idea is that if you don’t maintain the source code to something, you should not be mocking it.</p><p>By mocking the <em>request</em> library in tests, this adage was broken, and you’re paying the price. Now you must go and update all the calls to mock <em>request</em> and instead mock <em>cross-fetch</em>. Ugh.</p><p>In the scenario with the wrapper, you can avoid this pain by simply mocking the wrapper. Instead of application code like the following:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3d78b46761af8a84b6df5ea0d9331902/href">https://medium.com/media/3d78b46761af8a84b6df5ea0d9331902/href</a></iframe><p>You would just reference the wrapper in your application code:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/dac61bffa6ff509ed5dbf295721f0ca0/href">https://medium.com/media/dac61bffa6ff509ed5dbf295721f0ca0/href</a></iframe><p>In the tests, you would now mock out the wrapper with a statement like jest.mock(&#39;./wrappers/request.js&#39;). If you went with this approach, when swapping the <em>request</em> dependency for <em>cross-fetch</em> you wouldn’t break any tests.</p><p>This should raise some eyebrows though… If you’re mocking the wrapper, won’t the tests fail to detect if the wrapper incorrectly adapted the <em>request</em> API to the <em>cross-fetch</em> API?</p><p>Yep.</p><p>This is why you MUST write integration tests for the wrapper. Ideally, you want to write tests for the wrapper that don’t mock anything and verify that swapping one third party implementation for another doesn’t break anything. In some cases this is more feasible than others. When writing an HTTP client wrapper, as in this example, instead of mocking the third party dependencies, you can use something like <a href="https://netflix.github.io/pollyjs/">pollyjs</a> to mock everything at the HTTP layer.</p><p>There’s also another, more insidious, scenario that you can run into when mocking third party dependencies. Imagine a scenario where there wasn’t a wrapper, you had mocked out <em>request</em>, and instead of trying to replace <em>request</em> with <em>cross-fetch</em> you were just looking to upgrade <em>request</em> from version 2.81.0 to version 2.82.0.</p><p>You bump the library, run the tests, and everything passes. Great! You merge the code and push to production only to watch all hell break loose.</p><p>That’s because 2.82.0 introduced a breaking change, but since you were mocking the <em>request</em> library and never executed any of it’s code during the tests, they pass with flying colors.</p><p>Again, this is a scenario that could be avoided by wrapping the dependency and writing integration tests for the wrapper. In that case, the tests that mocked the wrapper would happily pass, and the integration test would fail hard due to the breaking change.</p><h4>In Order to Form a More Perfect API</h4><p>One of the harder to quantify benefits of using a wrapper is that you can more accurately design an API based on your application’s actual needs. Although third party dependencies save time on implementation, they aren’t a substitute for design. In many cases, a third party dependency has discovered its API through lots of battle tested use. But often you’ll find that how your application specifically needs to use it is a little different than how the library has been designed.</p><p>Let’s go back to looking at <em>request</em>. For this example, we’ll be looking at how you would set up a scraping application that needs to specify some different sets of proxy configuration.</p><p>Let’s assume that you have a number of different scraping “profiles” that you wish to use. Each of these profiles will configure a couple things, such as a proxy server to use, some specific HTTP headers, and some specific authentication credentials. For example, you’ll have a US-EAST profile that requires one specific Authorization header for that proxy, and a US-WEST profile that requires a different Authorization header.</p><p>Requiring the calling code to specify profile specific Authorization headers everywhere you want to make an HTTP request is not ideal. Instead, you can just define each of these profiles with a name and its configuration inside the wrapper file. You’ll then modify the wrapper API to accept a profile parameter. This way, each of the calling sites doesn’t need to worry about the nitty-gritty details of HTTP headers but can instead just specify a specific profile to use.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/177616b55474dce2e1414e24cf048ed9/href">https://medium.com/media/177616b55474dce2e1414e24cf048ed9/href</a></iframe><p>The result is an API that better suits the use case which means that testing will be easier, and making modifications to calling code should be less coupled. Better yet, there are more clearly defined boundaries for the system such that any implementation concerns about how profiles are handled don’t leak into tests.</p><h3>Only Sith Engineers Deal in Absolutes</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AFBHco3_25Px8bPb8vY4Ew.jpeg" /><figcaption>You’re either with wrappers or you’re their enemy</figcaption></figure><p>Of course, like any choice in software design, there’s always trade-offs to using wrappers. For each case, you’ll want to ask yourself a few questions to determine if building a wrapper for a dependency is really worth its drawbacks.</p><p>At a minimum, adding a wrapper always adds extra work. There’s extra indirection, and now a developer can’t just go read the docs for the dependency to understand how it works. They might need to look at the source for the wrapper to really understand what contract the wrapper API provides. Good tooling can help you out a lot here. Using a fully featured IDE will provide things like tooltips with parameters and docstrings.</p><p>Adding a wrapper usually requires adding more documentation as well. Since you’re not dealing with the third party package directly, looking at those docs may be misleading, depending on what has been implemented in your wrapper. With modern tooling, I don’t tend to think this is that big of a deal. Using a static analysis tool like Typescript or Flow will go a long way towards telling you if you try to do anything too stupid.</p><p>As I mentioned earlier, you’ll always want to make sure you test this wrapper, which is another burden added to your codebase.</p><p>So when is this burden not worth it? I typically ask myself a few questions.</p><p><em>How close is this code to my core business logic? Is the code that uses this dependency or wrapper likely to change, or are my needs likely to change?</em></p><p>The less I understand the API contract I need, the less likely I am to commit to a wrapper right away. Otherwise, it can be a lot of wasted work that will just be thrown out when I discover that I actually need something totally different.</p><p><em>Is this a “commodity” library? Are there other libraries that exist which provide a similar service at the same level of abstraction?</em></p><p>Generally, the more of a “commodity” a library is, the more likely I am to wrap it. If a lot of libraries work at the same level of abstraction, there’s a good chance its roughly correct, and wrapping will allow me to replace or extend the abstraction to suit my application.</p><p><em>Is this an implementation detail? Is this just data manipulation calls to a functional library like Lodash?</em></p><p>Probably not worth wrapping.</p><p><em>Is this just too coupled/difficult/infeasible to wrap?</em></p><p>For something like an ORM, I would probably end up effectively implementing an in-house ORM just by trying to wrap an existing one. In practice, codebases rarely decide to actually swap out one ORM in favor of another, so little benefit is gained.</p><p><em>Is this an API client library, like Github’s </em><a href="https://github.com/octokit/rest.js/"><em>octokit</em></a><em>?</em></p><p>Choosing to write a wrapper here depends on a few things. Using the example of octokit, if you plan on supporting multiple git hosting providers, you’ll almost certainly be best served by writing an abstraction that sits above the specific library which could handle multiple providers. But if you’re just using a library to fetch data without a better abstraction, it might be overkill to wrap it. However, wrapping it will still prevent you from accidentally mocking it and dealing with false positive tests.</p><p>Some examples that come to mind which are good candidates for wrapping are: logging, HTTP requests, ui elements/components, generic string utils, or transactional email sending.</p><blockquote>You might have noticed that I suggest wrapping “commodity” libraries, like making HTTP calls, and I also suggest designing more application specific APIs as a benefit of wrapping. How can we wrap something that should be a fairly generic operation and yet also make its API more specific to our application’s needs? Just add another layer of wrappers! Sort of. If you find yourself with a wrapper API that isn’t quite at the right abstraction, feel free to move the wrapper down. For example, if your application had an HTTP wrapper that always added a specific header, and then you discovered that in one place, you need to make HTTP calls without that header, it’s perfectly okay to factor out a lower level wrapper from your initial wrapper which can be reused in places that don’t need the extra header. The important part is to make sure that you’re still only importing a third party dependency in one place.</blockquote><h3>“Implementation Details”</h3><p>In our case, we’ve found that the best way to implement this strategy is to take advantage of <a href="https://yarnpkg.com/features/workspaces">yarn workspaces</a> and build internal wrapper packages that provide clear boundaries. This makes them easy to package and distribute between multiple projects that we maintain.</p><p>If you’re not familiar, yarn workspaces provide a way to easily manage multiple packages within the same repository. Even if you have no intention of publishing these packages to a package registry, enforcing some isolation via workspaces can help ensure there isn’t too much coupling between discrete components.</p><p>To start using an HTTP wrapper, all we had to do was to add a new package to our monorepo: @resource/http . Now, we only import @resource/http wherever we want to make HTTP calls. If we ever find ourselves again needing to swap implementations for a different HTTP library, rather than having to update call sites everywhere, we only have to update @resource/http to coerce our wrapper API to the newly swapped implementation. This also means we can write tests mocking out @resource/http, and we don’t have to be afraid that the API signature will change on us, since we control it.</p><p>The important thing here is that we have the freedom and control to patch, fix, replace, and otherwise alter how we make HTTP calls without having to modify all the call sites in our codebase.</p><h3>And That’s a Wrap(per)</h3><p>Although you shouldn’t always wrap your dependencies, you should use your judgement to determine if it’s the right move while writing code. When determining if I should wrap something, I always ask myself:</p><ul><li>Is this a “commodity” library?</li><li>Do I have a good understanding for what abstraction I need in my application?</li><li>Am I sure this dependency isn’t too coupled or too much of an implementation detail?</li></ul><p>If I can confidently answer yes to those three questions, it’s a good indicator that the extra work of a wrapper will be more than worth it.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5fced2999616" width="1" height="1" alt=""><hr><p><a href="https://levelup.gitconnected.com/why-you-should-often-wrap-your-dependencies-5fced2999616">Why You Should (Often) Wrap Your Dependencies</a> was originally published in <a href="https://levelup.gitconnected.com/">Level Up Coding</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Implement Lazy Loading with Webpack and Netlify]]></title>
            <link>https://levelup.gitconnected.com/how-to-implement-lazy-loading-with-webpack-and-netlify-808d88081485?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/808d88081485</guid>
            <category><![CDATA[netlify]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[webpack]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Fri, 12 Jun 2020 13:26:01 GMT</pubDate>
            <atom:updated>2020-06-17T20:08:07.989Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2kzGCTm6Hq1uscycXHpJNw.png" /><figcaption>= potential pitfall</figcaption></figure><h3>Hand-holding Honeymoon</h3><p>The first time I used Netlify to deploy a single page app, I was pleasantly surprised. Before then, I’d usually used Heroku to deploy applications, which meant serving my index.html file from Heroku, and configuring my Heroku build process to upload my compiled assets to a CDN. While not too terribly difficult to set up, this process had some downsides. Serving the index.html file from Heroku meant that it could take extra time before changes were deployed to users and the performance wasn’t ideal. Netlify, on the other hand, deploys your index.html file and your assets almost instantaneously and it does so atomically. Excellent. However, there’s something that can be problematic about this: Netlify will only serve the current version of your assets at your specified domain.</p><p>In a lot of cases this doesn’t matter. You make changes, your application gets rebundled, and the next time a user visits your app’s url, they get the newest version of your app. Where this falls apart is when your app is designed in such a way that a user doesn’t necessarily get all of the required assets when they make that initial index.html fetch. A common case where this happens is when you lazy load pieces of your application. Check out the webpack docs <a href="https://webpack.js.org/guides/lazy-loading/">here</a> for a more thorough explanation and example of lazy loading.</p><h3>Cliff of Confusion</h3><p>The reason this doesn’t work is because a user may require an older version of one of your assets at an indeterminate time. For an extreme example, assume a user visits your website, anatomypark.com. They get served the index.html file which contains a reference to shell-abcdef.js . That file has a dynamic import() statement which loads pirates-of-the-pancreas-abcdef.js when a button is clicked. Now suppose the user doesn’t click that button and leaves their browser open for a week. Over the course of that week you’ve probably released a number of different changes to the site. This means that the names for your bundles have changed and are now shell-012345.js and pirates-of-the-pancreas-012345.js. The fact that shell-012345.js has changed doesn’t really matter, since that file is loaded when index.html is served to the user. But suppose that user returns to their open browser window, and tries to click that aforementioned button. Their browser will try to make a request to anatomypark.com/pirates-of-the-pancreas-abcdef.js which will 404 because Netlify is no longer serving that file.</p><p>That was a fairly contrived example, but you can imagine if you have written your app to lazy load a number of different files for performance reasons or by user type, that this scenario occurs more often than you might expect. This is especially true if you deploy dozens of times a day, like we do at <a href="https://www.resource.io/">Resource</a>. It basically means you can’t use lazy loading with Netlify without some extra steps.</p><h3>Desert of Despair</h3><p>There are a few ways to work around this. You could just bail on Netlify, but we’d grown to appreciate its instant cache invalidation and easy rollbacks, so we wanted to see if there was a way to make things work without switching to a different platform. Another option would be to set up Netlify to proxy these requests for old assets to some other place where you would need to store them, like an S3 bucket. Setting this up would require adding a few extra steps to our build process to always store our assets in that S3 bucket and we’d get worse performance for these requests since they’d have to be redirected from Netlify’s CDN to the S3 bucket. The final option we came up with, and chose to opt for, was to find a way to keep serving our old assets from Netlify. If we just kept copies of previously built assets around in Netlify, these old requests would work just fine.</p><p>Rather than keeping old assets available forever, we wanted to keep ~1 weeks worth of old bundle data around, so that old-ish bundle data is available for our users. We looked at two different ways to accomplish this: 1) Committing our bundles to our repository or 2) Using the persistence mechanism available in our build environment. We didn’t like the idea of committing build artifacts to our repo, so we started looking at the persistence available in CircleCI. One persistence option that it has is its <a href="https://circleci.com/docs/2.0/caching/">caching</a>, which is commonly used for caching dependencies. After some experimentation we figured out a way to abuse its caching mechanism in order to keep old bundles around. While these steps describe how to do this with CircleCI, you can probably adapt them to whatever build environment you’re in, assuming it has some persistence that you can use to keep your old bundle files around.</p><h3>Upswing of Awesome</h3><p>It’s easier to explain how this all works by showing the CircleCI config a bit out of order, since a single build job needs to access the bundle data from the previous build job. Don’t worry. There’s a full example a little ways down.</p><p>First, we have our build step. For now we’ll assume we’re doing something simple like running an npm script such as npm run build and we expect it to output our built index.html and js files to ~/build. We’ll also assume that our bundle files are created with unique hashes for filenames.</p><p>Second, once we’re done building we need to save that built data to our CircleCI cache. We do that with a step that looks like the following:</p><pre>- save_cache:<br>    key: bundles-{{ epoch }}<br>    paths:<br>      - ~/build</pre><p>This step tells CircleCI to cache our entire ~/build folder, and store it with the key bundles-{{ epoch }} which means we should get a strictly increasing key using the number of seconds since epoch. We really don’t care about the key itself. All that is important is that each set of bundle data gets a unique key.</p><p>The last thing we need to do, is make sure that the next time we build our bundles, we include the bundle data that was built during the previous build. This step is actually going to occur before our build step in our configuration file. We’ll do this by using the cache restore functionality that CircleCI provides. Cache restoration is done by cache key prefix, so what we can do is lookup all of our bundle caches using the key bundles. A crucial reason this works, is that when CircleCI encounters multiple matches for a cache prefix (and in this case it will match ALL previous caches) it uses the most recently created cache that matches. In our case, this means we’ll get the most recently built bundle. By calling restore_cache we’ll end up copying our most recently created bundle data into the ~/build folder. The step will look something like the following.</p><pre>- restore_cache:<br>    keys:<br>      - bundles</pre><p>Tying all these steps together, we should have a working set of operations that results in us restoring our previous bundle files every time we run our build job. The file should look like the following when tied together:</p><pre>job:<br>  steps:<br>    # Dependency installation and source code fetching omitted<br>    # for brevity<br>    ...</pre><pre>    # Restore the most recently cached set of previously built<br>    # bundle files<br>    - restore_cache:<br>      keys:<br>        - bundles</pre><pre>    # Build our current bundle files<br>    - run:<br>      name: Build Bundle<br>      command: &gt;<br>        yarn build</pre><pre>    # After we&#39;ve built our bundles we need to save them to<br>    # the cache so they can be restored during the next build run<br>    - save_cache:<br>      key: bundles-{{ epoch }}<br>      paths:<br>        - ~/build</pre><pre>    # Deploy to Netlify<br>    - run:<br>      name: Deploy to Netlify<br>      command: &gt;<br>        netlify-cli deploy --prod --dir=./build </pre><p>It’s important that we perform the build step after we restore previous bundle files, so that our build step overwrites any files that have changed, but don’t have unique filename, i.e. index.html.</p><p><strong>IMPORTANT: </strong>We need to make sure that our build step does NOT clear the ~/build directory before creating new bundle files. Otherwise, we’ll just remove all the previously created bundle files that were restored from the cache. This is the default behavior for create-react-app, so we had to work around this behavior. Unfortunately, there’s no easy way to disable it. In our case, we had already ejected from create-react-app, so we could modify the build.js script directly. Otherwise you may need to fork react-scriptsas described in the docs <a href="https://create-react-app.dev/docs/alternatives-to-ejecting/">here</a>, in order to modify the build.js script.</p><p>Once all this is said and done, we should have lazy loading working properly on Netlify.</p><p>Except….</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/321/1*Of2ydJ0nyS3oDaV9lrgmTw.png" /><figcaption>That’s a LOT of bundle files…</figcaption></figure><h3>Despair Again?</h3><p>After a couple days we noticed that the number of assets we were deploying to Netlify kept going up. Uh-oh. We’re always just adding the entirety of our previous bundle files to our new set of files, meaning our cache just keeps growing.</p><p>We decided to deal with this problem by just removing all files in ~/build that are older than 1 week. Again, since we had already ejected, making this change to our build script was fairly easy. We just added a small npm package called find-remove that provides that functionality via a function called findRemoveSync, but you could easily implement it yourself instead. The relevant part of our ejected build script looks as follows:</p><pre>const { checkBrowsers } = require(&#39;react-dev-utils/browsersHelper&#39;);</pre><pre>checkBrowsers(paths.appPath, isInteractive)<br>  .then(()) =&gt; {<br>    // Remove any files that haven&#39;t been modified in the last week<br>    const weekInSeconds = 60 * 60 * 24 * 7;<br>    const results = findRemoveSync(paths.appBuild, {<br>      age: {<br>        seconds: weekInSeconds<br>      },<br>      files: &#39;*.*&#39;<br>    });<br>    console.log(`Removed ${Object.keys(results).length}                                                                   files/directories`);</pre><pre>    // Merge with the public folder<br>    copyPublicFolder();<br>    // Start the webpack build<br>    return build();<br>  })</pre><h3>Job Ready</h3><p>And that should do it. With just a little bit of configuration, you’ll now be able to take advantage of webpack’s lazy loading while deploying to Netlify. This should allow you to more easily break up your application, which will help reduce bundle sizes and provide better performance for your users. Go forth and lazy load!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=808d88081485" width="1" height="1" alt=""><hr><p><a href="https://levelup.gitconnected.com/how-to-implement-lazy-loading-with-webpack-and-netlify-808d88081485">How to Implement Lazy Loading with Webpack and Netlify</a> was originally published in <a href="https://levelup.gitconnected.com/">Level Up Coding</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Prefer Blessed Ecosystems]]></title>
            <link>https://jpulec.medium.com/prefer-blessed-ecosystems-3d71345dd03c?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/3d71345dd03c</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Wed, 13 May 2020 06:15:33 GMT</pubDate>
            <atom:updated>2020-05-13T06:15:33.030Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*b0Q1LmvJQ2h5BGjs" /><figcaption>Not that sort of blessed.</figcaption></figure><p>Throughout my time as a software developer, I’ve noticed a pattern with the language and framework ecosystems that I tend to enjoy working with most; they generally operate as “blessed” ecosystems.</p><h3>What is Blessed?</h3><p>When I say “blessed”, I’m referring to two properties that these ecosystems possess:</p><ul><li>The components are explicitly designed to work together.</li><li>The components are designed so that they can be swapped out for alternatives.</li></ul><p>In essence, the creators of the primary component(s) of these ecosystems have explicitly “blessed” other components as being a good default choice.</p><h3>Examples of Blessed Ecosystems</h3><p>My favorite example of a blessed ecosystem is the <a href="https://www.djangoproject.com/">Django Project</a>. The project consists of a web framework that is meant to handle everything, including: database access, templating, authentication, and administrative tools. And while many of the components you need to build a web application are “batteries included”, you can often swap them out if they aren’t suiting your needs.</p><p><em>Not finding the Django Template Language flexible or fast enough?</em> Swap it out for Jinja2 instead. <em>Unhappy with making your users create another account?</em> Swap the User model implementation to use OAuth instead.</p><p>These components have been abstracted enough such that one can safely swap them out and expect the rest of the ecosystem to behave just fine. The Django Admin doesn’t have a problem if you decide to use Jinja for rendering your templates, for example.</p><p>Another instance of a blessed ecosystem in the frontend framework world is <a href="https://vuejs.org/">VueJS</a>. Vue is maintained as a set of quite a few different packages, all designed to work well together, which can be swapped out if necessary.</p><p><em>Unhappy with how Vuex does state management?</em> Swap in MobX or Redux. <em>Unhappy with the way Vue Router handles transitions? </em>Swap in Page.js. Vue even has a blessed set of testing utils that will take you pretty far.</p><h3>Why Prefer Blessed Ecosystems?</h3><p>There are a few reasons why I tend towards blessed ecosystems, why I think they are a great choice for new projects, and why I wish more ecosystems would adopt a blessed model.</p><p>It should not come as a surprise that blessed ecosystems tend to work together better than the alternative. By my own definition, a blessed ecosystem has components that have been designed to work together. This means that they are likely tested together to ensure they work. Since these components are designed to be swappable, they also tend to be more modular and isolated. A common consequence of this modularity is simplicity, specifically the kind that Rich Hickey describes in his talk <a href="https://www.infoq.com/presentations/Simple-Made-Easy/">Simple Made Easy</a>. These components tend not to be too intertwined with other parts of the ecosystem.</p><p>In some cases, blessed ecosystems ensure that a set of projects get the required funding and attention, by consolidating maintainership. Vue-router and Vuex are maintained by the same group that maintains Vue itself, which means they’re not likely to become unmaintained or to lack available resources to fix issues. This consolidated maintainership also means that these projects can get the benefits of having the same code standards and processes for accepting changes. This makes it easier for others to contribute.</p><p>In these ecosystems, the blessed components are often either the defaults, or the recommended defaults in documentation. This results in a large set of users using this particular configuration of components. Most Vue users use Vuex for state management and Vue Router for routing. This means that when dealing with bugs, or searching for an answer on Stack Overflow, you’re more likely to find a useful result than if you were trying to figure out why a particular view library isn’t playing nicely with a given routing library.</p><p>Lastly, I think the biggest reason to prefer a blessed ecosystem is that it allows you to defer making many decisions until you really need to and likely have a better understanding of what trade-offs to make. When starting a new project, it can be paralyzing to have to answer questions like, “What state management library should we use? Or what templating library should we use?” Often, you won’t even have the necessary information up front to make a very informed decision. Will you be rendering templates that have to transform many objects for display and will be hot paths? That’s probably not a question you can answer until your project is fairly far along.</p><p>If you choose to work in a blessed ecosystem, when you do discover the characteristics of your application and its data, you will be able to swap out components that don’t satisfy your needs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*5Yu851XeVQoZSmBLgXEmAg.jpeg" /></figure><h3>Golden Path?</h3><p>One of my favorite posts about technology choices is Charity Major’s <a href="https://charity.wtf/2018/12/02/software-sprawl-the-golden-path-and-scaling-teams-with-agency/"><em>SOFTWARE SPRAWL, THE GOLDEN PATH, AND SCALING TEAMS WITH AGENCY</em></a><em>. </em>If you haven’t read it go check it out. In it, she outlines how to manage the complexity of multiple programming language ecosystems/tools while still maintaining developer agency. Her proposal is that an engineering organization should create a recommended list of default components, called the Golden Path, and commit to fully supporting those components. Individual teams may choose to deviate but they must support those deviations on their own.</p><p>Choosing a Blessed Ecosystem is like already having a Golden Path laid out for you. No need to worry about the unsupported interactions of disparate components; the ecosystem has committed to ensuring that they are fully supported.</p><p>I hope that more ecosystems see the value in providing a blessed set of options to their users and I encourage them to move in this direction.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3d71345dd03c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Git Worktrees: The Best Git Feature You’ve Never Heard Of]]></title>
            <link>https://levelup.gitconnected.com/git-worktrees-the-best-git-feature-youve-never-heard-of-9cd21df67baf?source=rss-d0c8058de852------2</link>
            <guid isPermaLink="false">https://medium.com/p/9cd21df67baf</guid>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[git-worktree]]></category>
            <category><![CDATA[git]]></category>
            <dc:creator><![CDATA[James Pulec]]></dc:creator>
            <pubDate>Tue, 28 Apr 2020 02:04:42 GMT</pubDate>
            <atom:updated>2020-05-02T13:40:07.032Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mHquwCmG-rJ4fUTNdFX1gw.jpeg" /></figure><h3>Before There Were Trees</h3><p>When I first started using git professionally, one habit I had was to frequently stash code. I’d be working on a particular feature and I’d see a Hipchat alert (yes, this was before Slack) about an error being thrown in production. I’d take a look at the stacktrace in Sentry, and find the offending section of code. From there I’d return to my terminal, stash my changes, open a new bugfix branch off master, and begin trying to reproduce the error locally.</p><p>Usually this process would happen without too much pain. If there were untracked files in my working tree, I’d just add them and stash everything. After I’d pushed a bugfix branch up to Github, I’d unstash my changes and unstage any of the original untracked files I had added. Occasionally I’d make a mistake and do something awful like accidentally trashing my untracked files, or uncommitted changes.</p><p>Other times, I’d be working on a feature, and I’d see a PR review request from one of my coworkers. I generally try to review code as fast as possible, and depending on how urgent the change was, I would stop what I was working on to review the changes. Again, this meant stashing my changes and pulling down the code locally to try out the new changes, and verify edge case behavior.</p><p>Eventually, I got frustrated with the pain of stashing and unstashing, and decided that I should just clone the repository into another directory, and I would use that copy of the repository for bugfixes and code reviews. And this mostly worked. However, it isn’t without its downsides.</p><p>One big issue with having multiple copies of a repo in different directories is that branches aren’t shared between them. Sure, you can set one directory to be a remote of the other, but it’s still painful to constantly be syncing branches. In practice, if you use a development model where all code gets pushed to a central repository like Github, this isn’t as painful. Similarly, if you use stashing a lot, as I did, it takes a tiny bit of work to apply a stash from my directory to the other as a patch.</p><p>Another issue is that each directory has its own .git directory. This means all sorts of configuration has to be duplicated. I use a fair number of git pre-commit hooks, so these now needed to exist in both directories. Again, there are ways to work around this, such as using symlinks, or possibly centralizing some of this config in your home folder’s .gitconfig, but it’s not ideal.</p><p>Finally, this process didn’t easily scale beyond the 2 concurrent repo case. When I found myself needing to halt my existing work, create a bugfix, and review a coworkers code all at the same time, I was faced with the prospect of cloning another copy of the repo. Cloning the repo wasn’t exactly quick, and again I was faced with the burden of copying and keeping in sync all the configuration I had for the existing two repositories.</p><h3>Enter Git Worktrees</h3><p>Git Worktrees are a feature that allow you to have a single repository with multiple checked out working branches at the same time. Now that may not sound that cool, but let me lay out an example.</p><p>I have a copy of the ApertureScience repository located at /home/James/Aperture. I’m going to begin working on a new feature, cake. Before I start this work, I’m first going to run git worktree add cake. This will create a new directory for me to do my work located at /home/James/Aperture/cake. I spend a few hours working on my cake feature.</p><p>A wild error appears in our production app. Probably a rogue test subject causing trouble… Better go deal with that.</p><p>I stop working on the cake feature and run the command git worktree add bugfix inside the /home/James/Aperture directory. This almost instantly creates a new working copy of the repository at /home/James/Aperture/bugfix on a new branch called bugfix. I cd into that directory and run whatever commands I need to boot up the application. Once I discover the bug and figure out what changes need to be made to fix, I commit the changes, push up my branch for review, and then return to the feature work I was doing on /home/James/Aperture/cake. No stashing hassle, and no worrying that my most recent pre-commit hooks aren’t running.</p><p>Effectively, you can work on as many things in parallel as you’d like and can feel free to just pause your work and come back later.</p><p>Why aren’t more people talking about Git Worktrees?? They’re incredible!</p><h3>Can You Really Have Your Cake and Bugfix Branches Too?</h3><p>Of course, there are some downsides to be aware of when using git worktrees.</p><p>If you’re not stashing your code, or being forced to commit it, you’re more likely to just leave code in a working state. Usually, this is fine, but it means that you may not have any refs in the reflog if something goes wrong, or you may be less likely to have a committed copy of your code somewhere if you suffer a disk failure.</p><p>It’s possible that being able to work on more things at once may also be detrimental to your productivity. You might wind up splitting your focus and try to do too many things in parallel.</p><p>Finally, some tools may not fully support worktrees well. Worktrees rely on the fact that git allows .git to be a file that points to a directory, instead of an actual directory. Some tools incorrectly assume that .git must be directory and run into issues with worktrees.</p><h3>Recommended Setup</h3><p>I tend to try to keep things tidy, so I have my worktrees setup in a specific fashion to allow me to work easily. My worktrees folder looks like the following:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZNmxY56jVFoZJQx2W98t5Q.png" /><figcaption>A nearly accurate representation of my worktree setup</figcaption></figure><p>/home/James/worktrees/.bare — This is the actual git repository, a bare instance. This stores only the repo metadata and has no actual working tree. I keep this in a separate hidden directory so that I can create new worktrees from this folder, but don’t accidentally try to check out a branch in the worktrees directory, which is an operation that can only be done in a working tree.</p><p>/home/James/worktree/.git — This file just points to the .bare directory.</p><p>/home/James/worktree/master — I always keep a copy of master, mostly so that if something comes up I can spin up a local copy of whatever is running in production.</p><p>/home/James/worktree/hotfix — This branch is kept as a place where I perform hotfixes. It happens with enough frequency that I keep a dedicated worktree around for it.</p><p>/home/James/worktree/&lt;feature&gt; — I have a number of different feature worktrees, which are divided by particular feature areas of the codebase.</p><p>I’ve tried a couple different schemes for how to organize these branches, and still think there’s room for improvement, but am fairly happy with having at least a master worktree that allows easily spinning up exactly what is live on master, and a number of feature branches that allow me to work on multiple things in parallel. I also like to keep around worktrees such as, dependencies where I can drop in, bump a dependency, and spend a few minutes working on getting our code base to work with a new version of the dependency.</p><p>As a bonus, if you use Docker-Compose, or any other tool that is isolated by directory path, you can have multiple copies of your application running at the same time. Docker-Compose relies on using it’s containing folder for as a name for the containers that are created and for managing running containers. Of course, to make this work, you need to make sure your application is able to properly isolate itself with dynamic port allocation, etc.</p><p>All in all, this style of working has made it so much easier for me to context switch when it is necessary, and provides me with small chunks of work that I can get done in less than 1 hour increments.</p><p>I consider git worktrees to be one of the secret weapons in my toolbox and could not imagine going back to developing without them.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9cd21df67baf" width="1" height="1" alt=""><hr><p><a href="https://levelup.gitconnected.com/git-worktrees-the-best-git-feature-youve-never-heard-of-9cd21df67baf">Git Worktrees: The Best Git Feature You’ve Never Heard Of</a> was originally published in <a href="https://levelup.gitconnected.com/">Level Up Coding</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>