Chapter 2: Starting a New Project
In The Beginning ...
Congratulations, now you've got buy-in from your organization! Your internal stakeholders, bosses, and team are totally cool with what you have planned. You do have a plan, right?
Don't be scared. It is usual to be nervous about putting your code out into the world for anyone to come by and tell you how wrong you are or how tabs are better than spaces. Open source, emotionally, is not always easy; as with many things on the internet, it allows people to semi-anonymously tell you about your flaws. It's important to keep in mind that 1) you likely made a mistake or two, and 2) everyone makes mistakes. Try not to take things personally and view all comments as happy little constructive criticism there to make things better. As you do more open source, both starting and contributing, you will feel more confident and less concerned with the inevitable mistakes.
The lesson I learned early on when doing open source work is don't take things too seriously.
- Alan Palazzolo
This chapter will talk you through starting a new open source project, discussing first steps and introducing big to-dos and potential pitfalls/challenges.
The Naming of Things
Everyone knows there are only two hard problems in computer science: off-by-one-errors and naming things. There are an infinite number of articles on picking a good name. Identify your goal when naming your project. Are you trying to make a project that's easy to find? Make the name simple, clear and declarative. Are you trying to be creative? The world is your oyster! Generally, though, good names will be distinctive, descriptive and memorable.
Naming a project can be very important if it becomes a big success, but it's also something you can change down the line (sometimes with headache). So, take some time to think of a name you can live with, but don't over think it.
Choosing a License
When it comes to choosing a license, here are a few tips to make this important, legally-binding decision less scary.
Consider your organization's internal needs. Are you planning to sell this software to other organizations? Do you have strict rules about intellectual property that would prevent you from allowing others to modify and build on your work? You might need to check with your legal team on this, but if it's not already clear, you'll want to walk into their office with a plan.
Talk to your organization's legal counsel. Your individual license decision might not matter if your counsel recommends a different license for reasons you aren't privy to.
The NYT's counsel recommended we use the Apache 2.0 license instead of the MIT license not because of something intrinsic to how the licenses worked but because our counsel was more familiar with Apache 2.0.
— Jeremy Bowers
Take a look around at how similar organizations are licensing their open source releases, or consider the license most commonly used by the software community you expect to contribute to your project. Building a WordPress plugin? Browse through the plugin directory and follow the path that makes sense for you.
Review a list of common licenses and what protections they have to offer. Check out resources like choosealicense.com, from GitHub, or research popular licenses such as the MIT License and the GPLv3 to find the one that fits your needs.
Think about who is going to use your code. Though the potential may be anyone, what license you choose can affect how certain groups or organization can use your code.
There are many licenses to choose from, and you should pick the one that is best for you. To help narrow it down, there are essentially two types of licenses.
Copyleft. Copyleft license say that anyone who uses the code can reuse it, but the license goes along with the code, usually meaning that derivative work can only be distributed under the same license. The main plus of this license is that it continues "open source". The main negative of these types of licensing is that it can sometimes conflict with internal policies and make it hard to for certain organizations to use (usually commercial).
The most common of these the is the GPL license, the newest of which is the GPLv3.
Permissive. A permissive license is basically a license that says the user can do whatever they want with the code, sometimes requiring attribution. The main pro of a permissive license is that anyone can you the code regardless of specific restrictions they may have. The main negative is that not requiring that the use of it remain open source goes against the ideals of open source.
The most common permissive license is MIT.
Use the MIT license. The MIT license is the most popular license used on open source projects. It is very simple and allows users of the code to do what they want. If you don't have specific needs in your organization that lead you toward a different license, consider using the MIT license. In fact, it's so short, we can include it here:
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Licensing non-code projects
The licenses above focus on the reuse of code, but it's also important to license other assets you might be open sourcing, like images or raw data. Without an explicit license, some users may be prohibited from using these assets, whether by local laws or by their employer's policies. Including licenses for all pieces of your project is the best way to clarify a user's rights.
The most common license for non-code assets is Creative Commons, which is a suite of licenses made to be easy to understand and mixed depending on your needs. Creative Commons is mostly used for media or content, such as text, images, or videos.
The Open Data Commons is similar to Creative Commons but is focused on data. OpenStreetMap, a very successful open data project, uses the ODbl license.
It's important to note that licensing a open source project does not mean that you are giving away your copyright to that material, personally or as an organization (depending on how copyright works at your organization). A license is basically answering the question of "Can I use this? And how?" for everyone.
On the flip side, any contributions by other people or organizations are still copyright to those contributors. If your project becomes large enough, it may be worth looking into a Contributor License Agreement, so that both the project and the contributor have more defined rights/roles.
Know Your Audience
As with all product releases, news apps, or stories, you should probably have an audience—in this case, we're talking about users—in mind. Who are the users out there in the world clamoring for a thing that does what your thing does? You should keep them in mind throughout this process, not just to build the thing that serves their needs, but to build it in a way that makes it usable!
For example, if you're building a tool that small nonprofit newsrooms might want to integrate into their content management systems, consider the systems many of them use now and the resources they have on hand to vet and install new code.
Evaluate the Competition
The Internet is full of things. So many things. You want your thing to be one of them. Are you sure there's not already a thing that does that thing?
There might be. Consider whether this is a moment to stand on the shoulders of giants, building on an existing open source project, making it your own, and releasing it back into the wild for others to do the same, or if this is a moment to break from the past and build a much, much, better mousetrap. To mix metaphors, this is the moment when you're going to decide whether to reinvent the wheel, and sometimes, you have to do so if you want to get to the flying cars.
Spend some time searching for similar projects in the wider news nerd community, and beyond on GitHub and elsewhere. If you find an amazing repository you might want to build on, take a closer look at open issues, the recency of pull requests and commits, and get a feel for whether it's actively being maintained. Then, get in touch with the owners and find out what they learned along the way.
More on Getting Started
- "Producing Open Source Software," by Karl Fogel. Chapter 2: Getting Started
We're so excited for you right now. You've started your first open source project!
But wait, there's more. Skip to Chapter 4 to learn more about your first release, writing detailed and useful documentation, growing your community, and the inevitable end of your project. Or, if your task is to open source an existing project, make your way to Chapter 3.
- [ ] Name your project
- [ ] Choose a license
- [ ] Identify your audience
- [ ] Evaluate the competition
- [ ] Consider recruiting partners
- [ ] Create or fork a repository
- [ ] Start writing your README documentation
- [ ] Add your license and initial contributors documentation
- [ ] Commit some code!
- [ ] Commit some more.
- [ ] Update that README documentation
- [ ] Build your first release
- [ ] Have a plan for maintenance and support
- [ ] Have a contingency plan for sunsetting + other bad things that might happen