Forem: julia ferraioli

Open source and social systems

julia ferraioli — Fri, 09 Dec 2022 12:37:15 +0000

Free/libre open source software (often referred to as FLOSS, FOSS, or OSS ¹) exists to reclaim the ability to freely collaborate after the 1978 report from the United States's Commission on New Technological Uses of Copyrighted Works (CONTU) and subsequent 1984 Third Circuit Apple Computer, Inc. v. Franklin Computer case which rendered both compiled software and source code copyrightable ².

This was a victory for corporations, who increasingly saw the sale of software as a major revenue stream and therefore FLOSS as a threat. While proponents of FLOSS cared primarily about the freedoms and creativity that open source software development granted them, the mechanism they used to push back against proprietary interests was legal: licenses that outlined the rights and responsibilities of developing and consuming FLOSS.

These licenses (and the definition of open source) revolved around the output of open source development, and that shaped the narrative of open source that still exists to this day. Little focus is on the social systems that produce open source software, which include the relationships, environments, and structures that underlie FLOSS. These social systems, often referred to as sociotechnical systems, cannot be separated from the output of FLOSS without fundamentally misunderstanding open source.

Sociotechnical systems are an integral aspect of the various ecosystems that comprise the overarching open source ecosystem.

It is helpful to frame open source as many different, interacting ecosystems. They evolve, respond to stimuli, compete, collaborate, have cultures, and follow norms. Actions that impact an open source ecosystem can have ripple effects beyond that ecosystem – and beyond the world of proprietary technology or even technology altogether.

Well-meaning initiatives or regulations can shift the open source landscape in unpredictable ways, and affect the ecosystem for years to come.

Bringing in experts with an understanding of complex networks and social sciences can help navigate these ecosystems, and provide insight into the ramifications of external forces.

Shifting the view of open source from the resulting code to the social systems that create the code is critical when driving towards long-term sustainability of technology as a whole.

Major (or minor, depending on your perspective) differences exist between FLOSS, FOSS, and OSS; for the sake of readability this article uses FLOSS as the overarching term. ↩
I am not a lawyer and none of this should be construed as legal advice. ↩

How to empower your open source users and contributors

julia ferraioli — Sat, 04 Jun 2022 15:20:11 +0000

This article is cross-posted from The Lead Dev and juliaferraioli.com.

When the concept of open source first emerged, people collaborated on projects very intentionally. Without today's vast internet and information retrieval systems, the network of people (largely researchers) working on these shared systems largely grew via word-of-mouth. If you were working on a piece of software with folks outside of your institution, you likely would have communicated with them directly prior to them ever viewing a single line of code.

Even as more of the world gained access to the internet, finding information was a challenge. Usenet, a distributed discussion platform that came out of University of North Carolina at Chapel Hill and Duke University in 1980, arrived on the scene as a popular way to discover and communicate about software with freely available source code. Still, the effort needed to start using or contributing to a new project was high.

In order to find resources that you needed, such as source code or documentation (if any existed), you’d generally have to contact the author of the project. But eventually, web search improved, and with the rise of hosting and distribution platforms such as SourceForge it became much easier to find information about how to use and contribute to open source. Improvements in infrastructure, hardware, and computer science reduced the cost of experimentation and simultaneously increased the reach of freely modifiable and distributable software.

Barriers to people embracing open source started falling away.

Breaking down the barriers to open source

Open source is more accessible to new contributors than ever before, in part due to the user experience improvements pushed forward by platforms such as BitBucket, GitHub, and GitLab. They provide a way to discover new repositories and view their source. This means that you can browse and understand a project before becoming deeply invested. It has the added benefit for people with resource constraints, such as disk space or network bandwidth, because you no longer have to clone an entire repository (copy the files to your computer) in order to view its contents.

That said, there's still a fair amount of improvement that can be made to the open source experience.

Four ways to empower open source users and contributors

Last time, we extended the initial social model of open source by outlining why open source projects should provide information about how they operate. This time, we'll explore how projects can take a similar approach to helping users and contributors engage with them.

1. Documentation

Technical documentation existed long before the first line of code. Good documentation rests at that intersection between art and science, with technical writing expertise being highly sought-after in open source projects. Creating documentation for open source poses several challenges, including the sheer variety of audiences that need the docs! One of the most effective ways that a project can lower barriers to becoming involved is by specifying not only where documentation lives but also what type of documentation is available.

Consider the example set by the Python programming language, which points to several sets of documentation targeting different skill levels and roles.

2. Issues

While many projects these days choose to take reports of issues alongside where their code is hosted, some prefer to use an open source or third-party solution, such as Bugzilla or Trac. Wherever a project takes reports of issues and discusses them, making it very clear where community members should report current issues makes it an easier experience for them. As a side benefit, it lowers costs for maintainers by reducing the amount of redirection they need to do.

Jaeger sets a good example of this, by specifying where its issue trackers live, as well as where to file various types of issues.

Bonus points if a project publishes guides or templates for how to file issues!

3. Discussion

The frequency of communication between maintainers and users is of increasing importance to adopters, and can be a factor when making technology decisions. However, facilitating conversation between contributors and users alike signals a thoughtfulness and intentionality that benefits all participants in the project's community. Projects that make a point of documenting official channels for discussion encourage the growth of a healthy community, allowing community members to support each other.

An example is how Apache Beam lists its various discussion fora and when to use each.

4. Contributing

As the complexity of software increases, so does the complexity of contributing to open source. Projects may have language-specific style guidelines that they ask modifications to follow, or processes that must be adhered to when a new contributor wants to pick up a bug to fix. While these working agreements might on occasion seem overly prescriptive to prospective contributors, they are there to maximize the success of everyone involved. Contributors minimize the amount of wasted effort, and maintainers minimize the amount of back-and-forth answering questions and requesting changes in reviews.

Generally, setting these expectations improves morale!

Inkscape's CONTRIBUTING.md file outlines some general guidance as well as instructions about decision-making, building, testing, and documentation.

Along the same lines of providing contributor guidelines is documenting processes that architectural development should follow, such as how Bazel calls out how to make larger-scale changes to the core project.

Reflections

Another way to think about open source is through the lens of empowerment. You are empowered to see the source code of the software you use. You are empowered to modify it, distribute it, and learn from it. So why not take that to its logical conclusion and empower your community members with the information they need to be productive with and within your open source project?

These are just a few community-focused elements that you might consider through our social model of open source, though they are common to many if not most projects. (There are a few missing elements from our social model that we will address in the subsequent post.)

The next time you are updating the README for your project, review it to see if you are empowering your community with resources that will make them successful, whether as users, contributors, or future co-maintainers.

Why open source projects should embrace operational transparency

julia ferraioli — Sat, 04 Jun 2022 15:18:30 +0000

This article is cross-posted from The Lead Dev and juliaferraioli.com.

From operating systems to CSS frameworks, open source gives creators the ability to accelerate development, learn from communities of experts, and incorporate thoroughly-reviewed code. At its heart, open source concerns freedoms relating to code, but an open source project is a complex system that happens to focus on code.

In my last article, we started to explore how we might move past the typical focus on the open source license and instead develop a social model that captures additional complexity. As a recap, we established that the technical model of open source describes what you can and cannot do with it, typically by way of the project's license, whereas the social model describes how open source interacts (or doesn’t) with the larger ecosystem and the people within it. That initial article addressed capturing the purpose of a project based on its specific goals within the open source ecosystem.

In this second piece, we will continue to develop the social model of open source by exploring the benefits of operational transparency, and outlining some key characteristics that maintainers should aim to make publicly available.

The benefits of operational transparency

A key benefit to open source is that anyone can examine the code they incorporate, but how the project operates is just as important to a project's success as the functionality itself. With open source making up an estimated 90% of today's modern technology, it’s increasingly critical to make operational information readily available to the public, so that you can empower contributors and users to evaluate projects based on the criteria important to them.

The operational characteristics of an open source project are often thought of as fundamentals to the teams behind them, and yet they’re rarely communicated well beyond the maintainers. This is a lost opportunity, as open source projects that clearly, concisely, and consistently articulate how they operate give contributors and users the social frameworks that they need to work well within the project.

Here are some high-priority details that projects should aim to make publicly available:

1. The decision-making model

A vital part of running an open source project is deciding how to run the project. While ‘governance’ is an ever-expanding term, its primary concern is around how decisions get made and who gets to make them. (The Open Source Way has a fantastic, comprehensive guidebook around open source governance.) Whether a project is managed by a benevolent dictator for life (BDFL) or is foundation-backed, clearly communicating the model in use benefits potential contributors and project alike.

An example is Node.js which openly shares that it follows a consensus seeking decision-making model.

2. The project's affiliations

As more companies start to create open source as part of their strategic initiatives, it can instill a healthy amount of skepticism in potential adopters. When a project is run by a corporation, decisions about the future of the project can (but not necessarily) become opaque to the end-user. That said, a corporate-sponsored project may also have the ability to focus on security, developer experience, and usability in a way that independent projects cannot, as they can leverage the time, talent, and treasure of the company.

By identifying the affiliation of a project, whether it be a company, government, non-profit, or individual, it allows consumers to make informed decisions based on their own strategy and values.

An example is TypeScript’s open affiliation with Microsoft.

3. The funding sources

While open source is free (as in puppy) to consume, it is most definitely not free to create. From bandwidth and infrastructure to time, costs can add up. For people looking to build products by integrating with open source software, the price of switching components can be high as interoperability between projects is rare. Exposing how the project supports itself provides a two-fold benefit: 1) people deciding on a technology can evaluate if the project fits their risk profile, and 2) current integrators can clearly see when a project becomes at risk of running out of capital.

Plus, financial transparency is right in line with open source values.

An example is Homebrew which has been openly funded by GitHub sponsors, OpenCollective, and Patreon.

4. The maintainers and the core team

As incidents such as log4j and Heartbleed have shown us, open source software that provides key functionality for many services and applications is often maintained by only a handful of people. Additionally, information about the people maintaining projects may be difficult to find, forcing users to trawl the project's metadata through mailing lists, commit history, etc… in order to determine the size of the core team. Effectiveness of a team may be dependent on the number of members, but there are many other variables that influence how well a team manages their processes.

Publishing an up-to-date list of core team members, even without any information beyond usernames, can signal when a piece of software is in danger of becoming under-maintained or effectively unmaintained. In turn, this opens up an opportunity for users to step up and offer to take a more active role within a crucial dependency.

An example is Font-Awesome which publicly shares its team list.

Transparency helps everyone

Openness is about more than just code; it is also about how we make decisions, how we support ourselves, how we prioritize issues, and how we delegate responsibilities.

Of course, the operational details that a project considers important may vary, and maintainers will choose to highlight those that are most relevant to them. A project in its beginning phase might not yet have a formalized governance model or funding, while a more established project may have a variety of defined roles and responsibilities.

But wherever possible, increasing transparency around how work gets done sets clear expectations for contributors, raises the visibility of when a project is in need of support, and reduces the amount of effort that falls on the maintainers' collective shoulders.

Keep an eye out for my next article where we'll explore how to incorporate dynamics and conventions around communication into our social model of open source.

A vision for a social model of open source

julia ferraioli — Sat, 04 Jun 2022 15:15:03 +0000

This article is cross-posted from The Lead Dev and juliaferraioli.com.

Open source software (OSS) in spirit has existed since the 1950s, when researchers and academics shared source code with each other, treating code as a common good. After a court decision rendered code copyrightable in 1984, the Free/Libre/Open Source Software (FLOSS) movement started in earnest. Just a few years later, the first license that embodied the spirit of open source was created, though it is debated whether this was the GPL or MIT.

Open source is software where the code is available for anyone to use, integrate, examine, modify, and distribute. Christine Peterson coined the term in 1998, and the Open Source Initiative crafted the commonly accepted open source definition (OSD) shortly thereafter. The OSD adds requirements that prohibit discrimination against people, groups, fields, or technology. Because of the complex legal, technical, and social criteria around open source, most of these are covered by a license attached to the software.

That said, there’s so much more to open source than what fits into a license. It does not cover development philosophies, social structures, governance, or anything else that makes open source the rich ecosystem that it is today.

Technical model versus social model of open source

Defining open source by what you can and cannot do with it is the technical model of open source. It describes the minimum set of criteria for what software needs to do for others to be able to safely use it. This technical model works for establishing this baseline, giving everyone assurances that they can use software without getting into legal hot water.

Some take the position that software is not open source unless it accepts contributions, or has a governance structure, or has maintainers actively engaged with their users. People bring their own opinion to what open source is, and that can lead to mismatched expectations.

Instead of overloading the technical model of open source, we can overlay a social model that adds nuance and further describes aspects of a project.

The social model of open source describes the sociotechnical expectations of how open source interacts (or doesn’t) with the larger ecosystem and the people within it.

I’ll be writing a series of articles defining the characteristics of a social model of open source. In this first article, we will start developing this model by considering the purpose of different open source projects.

Breaking down open source projects by purpose

The first step to creating a social model of open source is to think about how projects differ from each other.

In her book Roads and Bridges: The Unseen Labor Behind Our Digital Infrastructure (pp. 20-21), Nadia Eghbal takes an analytical approach, describing different categories of software based on their function: frameworks, languages, libraries, and servers. These categories frame how software is used by developers or end-users, and help people find and identify open source projects of interest.

With a social model in mind, let’s take a different approach to categorizing projects, and instead consider the high-level purpose of _why _something is open source.

Below are a few example categories that can apply to open source projects. Focusing on the purpose (or purposes) of open source projects allows everyone to better understand the motivations of projects and have realistic expectations for how the project will operate.

Collaboration

Most well-known, larger projects fall into this bucket. Collaborative projects are what many people think of when they hear the words open source. They aim to bring the expertise of a wide range of people to build technology, together. Examples of collaborative projects include

Python and Kubernetes.

Demonstration

Demos are often snapshots in time, created to showcase an aspect of technology. They are typically small, self-contained, and single-purpose. Demonstrative projects can range from the practical stress-testing of a particular feature to creative, wacky ways to use them. Examples include WebRTC samples and the Dependabot Demo.

Education

With all the different frameworks, languages, tools, and more available to developers, educational projects are invaluable. Educational projects demonstrate best practices, patterns, and concepts. These projects are open source so everyone can learn from them. Examples of educational projects include Intro to Vue.js and Whispering Gophers.

Validation

We have seen how important validation and verification is for reproducing results in research, which is why more and more journals and conferences are requesting that article or paper submissions are paired with reference implementations. These projects rarely see updates or bug fixes, but it is important for them to be open source in order for others to study the code, learn from them, and incorporate the methodologies into their own applications. Examples include ACORN and LMSOC.

Facilitation

Projects whose purpose is facilitative generally help people use other technologies, most often proprietary technologies. These may be tools, SDKs, or other utilities. It is useful for them to be open source so that developers can extend or customize them to suit their own purposes. Examples of facilitative projects are ld-find-code-refs and the Netlify CLI.

Experimentation

The vast majority of open source projects in the wild fall under this characterization! These are the seeds of new projects, projects that are for tinkering around, and aren’t necessarily ready or even intended for others to use. Examples of experimental projects include Tex Customizations and install-next.

Developing the social model, together

The purpose of open source software is just one characteristic of a social model. There are others that we can and will explore together in future articles. By developing a shared understanding and vocabulary of open source beyond the license, we help maintainers, contributors, and users communicate and collaborate in a way that enriches the spirit of open source.

Why your git email address matters

julia ferraioli — Sun, 10 Apr 2022 20:02:31 +0000

Cross-posted from juliaferraioli.com

When you were getting started with open source – and especially with git, you probably ran across guidance that told you to run commands such as this:

$ git config --global user.name "Your Name"

$ git config --global user.email yourname@example.com

to set your git username and email address.

It's an easy way to make sure that whichever repository you're contributing to, and wherever its canonical source lives, your commits are associated with you. Effectively signing your name or open source identity to your commits is a Good Thing™, because it allows the project to identify recurring contributors, (selfishly) provides people like me a way to do some analysis on git data, and more.

That said, the email address that you use matters.

We all operate in different contexts. I have personal, volunteer, side-project, and corporate contexts – and different email addresses associated with each of them. The email address that I use for a specific commit tells the project in which context my contribution has been made.

So in addition to (or instead of) running setting a global configuration for your email address, you can run:

$ git config user.email yourname@company.com

within your clone of a specific repository to configure the email address that your commits should use. If you have set a global user.email as well, that's what commits will use if you haven't set one within a repository (git-scm documentation that describes this behavior).

As open source gains traction in nearly all (quite possibly all) industries with more companies and organizations contributing back to open source projects they use (also a Good Thing™), it is important to signal under which context people are contributing. Am I being a good open source citizen by fixing bugs in a framework that my employer uses? Am I trying to improve a library that opensourcestories.org uses? Or am I contributing because I find the project interesting?

These are some possible scenarios where the additional information provided by your commit's email address can give maintainers more insight into your motivations.

It's a bit more work for you, but transparency is a core value of open source. Be transparent about your affiliation, and be thoughtful about your email address!

So you're working from home: a primer, part 2

julia ferraioli — Wed, 11 Mar 2020 04:00:00 +0000

Hopefully you’ve identified rituals for your “commute” and have set up your space in a way that’s conducive to work. But how do you go from turning around and asking your colleague a question to communicating and collaborating in a much more...intentional way?

The virtual “turn around” (🎶bright eyes🎶)

If you work on a team that’s used to being largely in person together (or in clusters), working from home is going to hit you pretty hard. There are a number of ways to create a virtual space for communicating off-the-cuff, from low-bandwidth to high-bandwidth:

Team chat/Slack/etc... you may already have one, but if you’ve been working in an office setting, your group chat has likely languished. Revitalize it!
Create a social channel for your team on Slack/IRC/etc… it’s tempting to only communicate for work, but you socialize with your team as well. Make a space for pet pictures, articles, survival tips.
Schedule a q&a meeting every day, or a few times a week, have a 30 minute meeting dedicated to asking the questions that pop up. This does require some attentiveness -- write down your questions and bring them to the meeting.
Create a stable video call (Hangouts Meet, Zoom, etc…) that people can drop into when they’ve got a question, or even when they just want company.
Hang out virtually with your colleagues all day on a video call! Don’t turn that video off. STARE DOWN YOUR COLLEAGUES ALL DAY.

Which to choose depends entirely on your team’s habits and personality, but make sure you’ve got buy in from the whole team. It only works if the team is on board!

Making virtual meetings not suck

Let’s face it, many of us only tolerate meetings in the best of times. Believe it or not, virtual meetings can actually be better than in-person ones. However, it takes some work.

First, do you really need that meeting? If you can’t set an agenda or have a clear goal (and that goal can definitely be something like “reduce social isolation”) then it’s an email waiting to happen -- and probably always was. Or, if it’s a working session, consider just setting up dedicated time on the calendar to work on project x, and don’t make people join a meeting at all. Your team members are adults; you don’t need to see them working to know that they are.

If you’re going full steam ahead with a video call, lay down some ground rules. You’re going to have a bunch of isolated folks eager to talk. Have one person lead the meeting, and it’s got to be someone who will keep track of the agenda and time. Navigating participation will be a bit harder. You can go full out formal and make people raise their hands to talk, or you can have the meeting lead make sure that everyone has their voice heard. Their favorite phrase may become “I believe that Wonder Woman was saying something; let’s go back to her.” Finally, have a rotating note-taker. Having concrete notes makes it easier for people whose connections drop, or who can’t make the meeting.

You’ll note that those recommendations are just as applicable to in-person meetings as they are to remote ones. That’s by design! These habits are good to get into in general.

Combating isolation

As I mentioned, work isn’t just about getting stuff done; it has a social aspect as well. If your colleagues are following the recommendations at staythefuckhome.com, then they’re going to be combating social isolation. Manufacture some excuses to not talk about work. Here are some ideas:

Start a costume contest with household items (h/t Amanda Casari)
Hold serendipity calls where you talk about random topics, like what you’d do if aliens landed (h/t Megan Byrd-Sanicki)
Create a team book club, but with topics (Pluto, the color green, dinosaurs, salt versus sugar)
Eat lunch together! Share your recipes with each other.

It’s a difficult time for many, so be aware that your colleagues may be stressed. Above all, be kind to each other.

So you're working from home: a primer, part 1

julia ferraioli — Mon, 09 Mar 2020 04:00:00 +0000

With so many people suddenly working remotely, I thought I’d share some tips that I’ve learned over the years as I’ve worked from home. As many are discovering, it’s not just a matter of opening up your laptop on your couch and getting to work. There are lots of distractions and differences -- some subtle, some not -- when working from home.

Getting ready and winding down

If you’ve been working from an office primarily, you probably have a commute. However stressful or relaxing it might be, it’s a period of transition. You’re gearing up for work or mentally setting it aside. I’ve learned that I can’t just stop working for the day and dive into “home mode;” if I do, my partner gets work-me instead of partner-me.

Try to build a “commute” into your day. This could take many forms:

Chat with your partner
Make yourself a longer breakfast (news reading as you see fit)
Take the dog/iguana/cat/self for a walk
Do some light straightening/cleaning up
Write an email to a friend

This puts some time in between work and the rest of the day, giving your brain the mental buffer that it needs to prepare or relax.

Preparing your space

I am lucky enough to have a room that I’ve made into an office, but I realize that this isn’t an option for everyone. Wherever you choose to work, make it your space for work. This might mean setting up a monitor, or putting your notebook, whiteboard, fidget toy, and chapstick nearby.

If you do have a desk, lay it out as close to your office desk as you can. Keep it as clean (or messy) as your office desk usually is. Take some time to check your ergonomics; you’re going to be here for some time, not just nights and weekends. Things that don’t annoy you in the off time will suddenly become intolerable during working hours, so try to anticipate them in advance so you can fix them.

Getting down to work

Working from home requires a bit more discipline than working in an office. Everything that you like to do in your off time is now at your fingertips! So that means there are lots of -- ooh, shiny object! That would look great on my side ta -- distractions. Your brain will still be putting together grocery lists, brainstorming ideas for dates, and thinking about the last episode of <insert favorite TV show here>.

In addition to preparing the space you’ll be working in, get into a ritual of setting things down. Physically put away your tablet, turn off or suspend your gaming rig, clear your work space of non-work stuff. If something is still nagging at you, get it done and set it down. With the example of a grocery list, round it out on your phone or notebook and then set those behind you.

Keep yourself accountable. Each day, in your team’s Slack/chat/IRC, say what you’re aiming to accomplish. This is your work version of a gym buddy. Or, you can ask someone on your team to be your work buddy, and you can keep each other accountable. Introvert? Make a checklist instead, and check off those items (preferably with a flourish, but you do you).

That’s part 1! In part 2, I’ll talk about collaboration and productive meetings.

Using buffer to set image descriptions

julia ferraioli — Mon, 11 Mar 2019 14:03:04 +0000

This is cross-posted from my blog.

Descriptions on images, also known as alt-text, are important for people reading your content using a screen reader or other assistive technology. Screen readers synthesize on-screen text, which allows people who are blind or have low vision to interact with technology. However, images cannot be "read out loud" the same way that text can, so screen readers rely on the person posting the image to set the description via alt-text, and synthesize that property instead.

This used to primarily concern designers and software developers, who would make sure that each image had its alt-text properly set so that everyone could use what they built. Now, many sites rely heavily upon user content, which means that sites leave setting the descriptions up to the users who post the images. Unfortunately, providing these descriptions is not always very discoverable -- if possible at all.

**My typical flow to share images and setting alt-text**

I've been relying more and more on buffer to facilitate providing alt-text for different sites. This lets me set the description with services that allow it via the API (Twitter) while simultaneously sharing it to services that don't (Instagram, LinkedIn). If sharing a link, it also gives me the ability to select what image to use from the article, and provide alt-text for that as well.

Actually figuring out how to enter a description isn't super discoverable on desktop. You have to hover over the image itself to get the "add description" option:

**Adding image descriptions in a browser**

I like the mobile experience better, because the option to add the description is clearly visible:

**Adding image descriptions in the app**

That's how to set alt-text using buffer, but what should the alt-text actually be? There's a lot of guidance online, but this site explains some best practices for crafting the text itself. My rules of thumb are:

Be concise: alt-text will be read out loud by a screen reader
Aim for parity: convey the same information that you expect the user would glean from the image
It's not a caption: alt-text should provide information, not commentary

Hopefully, this gives you a strategy for making your social content accessible. I'll cross my fingers that more platforms will add support for setting alt-text, not just in their user interfaces but in their APIs as well, so that integrations like buffer can take advantage of them. Go forth and describe!

2FA, SMS, and you

julia ferraioli — Sat, 11 Aug 2018 12:47:06 +0000

This is cross-posted from my blog.

2-Factor Authentication (2FA) or Multi-Factor Authentication (MFA) are ways of securing accounts above and beyond normal password protection. Typically, we think of 2FA as something you know (your password) and something you have (a device). The idea is that if you compromise one, you still can’t get access to the protected resource.

Antique, ornate lock

A room protected by a keypad and ID card reader is a great example of 2FA. You might be able to guess the code, but you’d also need a valid ID card to get access to the locked room.

What about biometrics? Good question. Technically, still something you know (the password) and something you have (a retina/fingerprint/etc…), but stored biometrics make me nervous. I steer clear.

(Some) 2FA Options:

At a high level, here's how each works:

TOTP works via app, on your phone, browser extension, or command line, and generates you with a time-limited code to provide when logging into an account.

U2F works by configuring a device (you may have heard of Yubikey), and supplying that device every time you log into an account.

SMS works by getting a text with a code that you enter every time you log into your account.

2FA isn’t all that complicated in practice. It’s an extra step, yes, but worth configuring to protect your account(s).

However, not all 2FA is created equal. I have had to help more than one person recover accounts protected by SMS-based 2FA. SIM hijacking is when someone takes over your phone number and can therefore intercept your calls and texts. Some sites / apps who use SMS-based 2FA will allow password-resetting via SMS or voice alone. If someone hijacks your SIM, they can get access to those accounts without needing to know (or guess!) your password.

That’s why I recommend not using SMS-based 2FA. If you’re against carrying around an additional device, set up a TOTP app (like Google Authenticator) on your phone. Let’s face it, you probably carry it around anyway. U2F is my preference, but that can be a bigger hurdle if you’re just starting with 2FA.

Here’s a good general guide on how to set up 2FA. If you want to go the U2F route, you'll probably want to get a YubiKey.

Other best practices:

Recovery codes -- download them, store them.
Keep your passwords strong -- 2FA isn’t a replacement for a good password.
Use a password manager -- a trusted password manager can store the TOTP seeds, if you need to use more than one device.
Back up off-site -- for the truly paranoid, store backup codes, devices in an off-site, offline location like a safety deposit box.

Question: What if a provider only allows SMS-based 2FA?

Great question, but one there’s not an easy answer to. It depends on a lot of stuff. First, evaluate whether you really need that account. If not, then there’s no issue. If you do need that account…

Evaluate your risk profile. If this account is compromised, how much damage is it going to do? If it’s not going to do any, I might not recommend securing it with SMS in the first place. If it has the chance to do damage, then I’d investigate the policies of how the provider allows account recovery and make a call based on that. Definitely still use a unique password, and definitely make the request for other 2FA options!

Need provider-specific advice for securing your accounts? twofactorauth.org is a great way to figure out what they support and how to go about enabling it.

Have other questions? Let me know and I'll try to answer them.

Testing in Go: testing floating point numbers

julia ferraioli — Wed, 20 Jun 2018 12:25:21 +0000

This is cross-posted from my blog.

I've been working on a library that includes some vector manipulations in Go, trying to follow good development practices and starting with writing my tests first. But early on, I ran into a bit of a problem: floating points.

The problem

Now, we know that floating points are an issue in programming, by the very nature of how they're represented in memory. I loved Julia Evans's brief explanation of how floats work in her Linux Comics Zine (scroll down to the sixth panel), and for a more in-depth explanation, see this piece by Carl Burch.

My problem: after writing my implementation of a vector addition function, I couldn't get the tests to pass, because comparing equality of floating point numbers is...hard. I'd be comparing an expected result of {2,3} to an actual result of {1.99999999, 3.00000000002}. Those values don't pass muster for traditional equality.

I looked up best practices of how to unit test functions that returned floating point numbers and overwhelmingly found the recommendation of "don't". (Not helpful, y'all.) One recommended using a tolerance -- that is, if the absolute difference between the expected number and the actual number was under a specified tolerance, you counted them as being equal.

That was pretty easy to implement, and it looked like this:



got := Add(tt.vectors)
if math.Abs(got-tt.want) > tolerance {
    t.Fail("Got %v, expected %v", got, tt.want)
}

Defining a comparer

However, I recently started to reimplement my library, and in the process switched over to testing using the cmp package. The cmp package is a much more robust way of testing for equality, and in exploring it I found that you can define a comparer function that makes this a lot cleaner. This is the comparer function from the documentation, which uses a bit more refined logic than my initial one above:



const tolerance = .00001
opt  := cmp.Comparer(func(x, y float64) bool {
    diff := math.Abs(x - y)
    mean := math.Abs(x + y) / 2.0
    return (diff / mean) < tolerance
})

Then, when you run your test, you use the comparer function when testing for equality:



if !cmp.Equal(got, tt.want, opt) {
    t.Fatalf("got %v, wanted %v", got, tt.want)
}

Your tests are much more clean, and you can easily use a comparer function that works for your use case.

Postscript

However... you have to be careful with your comparer function! The one above is straight from the cmp docs. But straight away I ran into a test failure that I didn't expect: when trying to perform operations on zero vectors, it failed, hard. Which led to this exchange between me and my tests:

Frustrated tweet, Twitter

Yep, when all the values in a vector are zero, I wind up dividing by zero. So my actual comparer function looks like this:



opt  := cmp.Comparer(func(x, y float64) bool {
    diff := math.Abs(x - y)
    mean := math.Abs(x + y) / 2.0
    if math.IsNaN(diff / mean) {
        return true
    }
    return (diff / mean) < tolerance
})

Of course, the same logic (diff / mean) would have had the same issue without using the cmp comparer option, so this amusing story is about the general case.

But, that said, it took 8 lines of code to make my tests actually test what I care about. So if you're doing scientific computation, don't forget about your comparer function!

Go test!

All code in this blog post is released under the Apache 2.0 license and can be found on GitHub.

Nevertheless, julia ferraioli Coded

julia ferraioli — Thu, 08 Mar 2018 15:46:44 +0000

I began/continue to code because...

I started to code in high school, in a computer science course that was half geeks and half people trying to fill a graduation requirement. I'm honestly not sure which group I belonged to at the start. We were the last year that computer science was taught in C++ (shoutout to Borland!) and I'm forever grateful for that.

Coding had me at "Hello, world!"

When I arrived at Bryn Mawr College, I was still pretty determined to pursue a different path, but took more CS classes for fun. And more. And more. I played with graphics, I caused kernel panics, I built robots and made them zoom around, I did nifty stuff with machine learning.

Before I knew it, this was my path.

I first fell in love with coding because:

I could make things, that weren't there before, happen
It was a codification of logic, which made sense in a world that didn't
Every new project was a new adventure with new problems

I still love coding because of the people. While the technical challenges are still enjoyable, I take deep satisfaction in building things that help other people.

I recently overcame...

Oh my. Well, I'm not exactly private about my health struggles. The last round of whatever-the-hell-is-wrong-with-me threatened my ability to see. I had no idea how I'd continue to code without my sight. Software bugs I can fix. Biological ones I cannot. Looking at a future without my chosen profession was terrifying and demoralizing.

While eventually I got my sight back, I had also started to develop a personal tool set for coping with low vision, that I think has made me a better engineer. I rely less on what I see, and more on internal reasoning. My mental scratch pad is a lot bigger now than it used to be.

I want to brag about...

I actually have a couple of things.

Open Source @ Google

My job at Google is dedicated to supporting open source. Most of the time, this means a lot of internal work to make sure that engineers at Google are supported in their open source efforts, and much of it isn't public facing. However...

While I was only involved in the starting phase for opensource.google.com, I helped with the initial design and beginnings of implementation for the project explorer. Not only does this showcase some of Google's open source projects, but it starts to show the depth of involvement of Google in the broader open source community.

I think it looks pretty shiny, too.

Can I Hug That?

Okay, so I'm still absurdly proud of the little demo I built using Google CloudML, "Can I Hug That?". (You can see a video of it in action here.)

From a technical perspective, this isn't hard to do. So I'm not bragging about the engineering side of it (and I really shouldn't; the server code is a bit messy). But I do want to brag about the concept, because the goal was to pick a problem that we couldn't use a pre-trained model to solve, make it clear why a custom model would be the right approach, and make it understandable and approachable without a machine learning background.

In short, I wanted to make machine learning friendly. I wanted to make machine learning huggable.

And, based on the feedback I got on the talk and demo, that's exactly what I accomplished. I am super proud of that.

I look up to...

I'd like to specifically call out Ashley McNamara for being an inspiration, both for her technical leadership and community leadership. Her path into and through software engineering is a shining example of determination and skill -- one that I hope to follow. And can we talk about her art? I’ve never seen such cute gophers in my life.

Lastly, Ashley reached out to me when I felt so stuck in my life that things seemed lost, and talked me through it. I don’t know if she realizes just how much that meant to me. Thanks, Ashley.