Get best of the week

Open Source Guides: Launching an Open Source Project



Translator's Preface


A couple of months ago on Github I stumbled upon the link "Open source guides" and could not come off. Somewhere in a week I carefully read all 10 sections. Of course, I already knew about open source: I read various articles (for example, “Understand Open Source” ), used such projects in my work, addressed questions to communities, reported bugs, scoured issues and even made clumsy attempts to then improve, at least the documentation. And of course, I was in heart with these guys who share software and knowledge on its use. However, the concept of open source was rather vague and fragmentary. And this article added clarity.

In addition, I had a couple of projects that I planned to launch in this format, with the hope of community support, and with many attendant fears and doubts, and again this article helped me establish my intentions and suggested practical steps.

Regardless of your attitude to open source, I think you will find in this series of 10 articles many interesting ideas and facts: organizational, psychological, legal, ethical and technical.

I let this non-programmer read this text, they said that they understood everything. And in the title of the article, I deliberately put the “source” without the “code”, because this topic is relevant not only for programmers, but for almost any intellectual activity in the format of an open project.

This manual itself is also open source and has already been translated into 14 languages. I was honored to add a Russian thread and a translation of the first article. I plan to continue to translate article per week. If anyone wants to connect, here is the repository: Open Source Guides .

If suddenly someone needs a screensaver from the heading of the article (illustrations + Russian names), then it is in a lay-out on codesandbox.io .

Selection of terms


I apologize in advance for the flaws in the translation. Some seemingly banal terms are not so easy to pick up in Russian. For example, to contribute, pull request, issue, I often translated as "participate in the project, propose corrections and a question." I left open source in English so far. I have already made a comment and sent a link to the dictionary of terms of Github . I did not like the abundance of transliteration there. If all these ishis, pullrequest, push, pool, fork are included in the article, then it will become incomprehensible to everyone who did not work with Github.

Yes, the issue can be a question, a task, a bug report, a sentence, etc., and it’s hard to find one Russian word that would convey all these meanings. But the English word issue is also without a particularly broad meaning, just the creators and users of Github have endowed it with such breadth. If we mean by the words “open a question on Github” that this question can be very different (bug, question, request for help, task, ...), then the word “question” will harmoniously replace the word “issue”. Also - push - send, pull - accept, fork - branch, etc. It is not the word itself that matters, but the meaning that we agreed to put into it. The British, who first come across the term issue on Github, also have to first read a description of all its possible meanings within the framework of this system.In the meantime, I take clarity as a priority for the maximum number of people who have not worked with Github. In any case, the selection of terms is in the process, and the entire translation, like the original, is open source, so do pull-quests and open with ish.


: ?
«open source»?
?
Open source — ?

open source ?



open source

README






, ( ) !






: ?


So, are you thinking about launching your open source project? Congratulations! The world appreciates your participation. Let's talk about what open source is and why people do it.

What does open source mean?


When the project code is open, it means that anyone is free to use, study, modify and distribute your project for any purpose. These permissions are granted through an open source license .

The advantage of open source is that it reduces the barriers to choosing your program and collaboration, allowing people to quickly distribute and improve projects. In addition, it gives users the ability to control the code, as opposed to closed. An open source software company (software) may hire someone to make improvements to the software, rather than relying solely on the decision of the open source vendor.

Free software refers to the same projects asopen source software (the open-source) . Sometimes you may find combinations of these terms : “Free and open source software” (free and open source software FOSS or free, libre, and open source software FLOSS). The words free and libre here mean “free,” not “free . "

Why do people make their work open?


avatarOne of the biggest rewards I have received from open source is the relationship that has been established with other developers who are facing the same problems as me.
@ kentcdodds , “How Great It Was for Me to Enter Open Source”

There are many reasons why an individual or organization opens the source of their project. Here are some of them:

  • : Open source . , Exercism, 350 .
  • : Open source , . -. WordPress, , b2.
  • Transparency: Anyone can check an open source project for errors and inconsistencies. Transparency is important even at the state level. For example, the Bulgarian government and the United States legislated transparency for industries such as banking, healthcare, and security software like Let's Encrypt .

Open source is applicable not only to software, but to everything else: from data sets to books. In the GitHub Review, you can get more ideas on what can be oversensitive.

Is open source free?


Free open source is one of its greatest benefits, but not its only, but rather a by-product of its combined value.

Since an open license implies that anyone can use, modify, and distribute your project for almost any purpose, in most cases this implies free of charge. Because if you asked for a fee, then people would download the project and use it for free, absolutely legally.

Therefore, most open source projects are free, but this is not included in the definition of open source. There are ways to charge for open source projects indirectly through dual licensing or limited features, but they comply with the official definition of open source.

Should I launch my open source project?


The short answer is yes, because regardless of the result, launching your project is a good way to understand how open source works.

If you have never run such projects before, you may be worried: “what will people say?”, “What if no one will notice him at all?” If this is familiar to you, do not worry, you are not the only one!

Open source, like any creative work, whether it be writing or drawing, causes excitement before sharing it with the world. But the only way to improve it is to practice, even if you don’t have an audience.

If you have not decided yet, take the time to think about your possible goals.

Goal setting


Goals will help you decide what to work on, what to give up, and where you need help from the outside. Ask yourself: “Why am I opening this project?” .

There is no single answer to this question. You can have many goals for one project, or different projects with different goals.

If your goal is simply to show your work and there is no need for cooperation, you can write in the README file. On the other hand, if you are interested in assistants, then you should invest your time in writing understandable documentation and take care of beginners.
avatar UIAlertView … open source. GitHub. , , . , - . .
mavris@mavris, « : Open Source »

As the project grows, your community will need more than just code. Answers to questions (issues), code verification, dissemination of information about yourself - all these are important tasks of an open source project.

Although the amount of time spent on non-programmatic tasks depends on the size and scale of your project, you should be prepared to solve them yourself or find an assistant for this.

If you are part of a company that launches an open source project, make sure in advance that you have internal resources for its development. Assign a post-launch support officer and determine how tasks will be distributed within the community.

If you need a dedicated budget or staff to advance, operate and support the project, discuss this as soon as possible.
avatarWhen you start an open source project, it is important that the management processes in the organization take into account the contribution and capabilities of the community that has formed around the project. Do not be afraid to involve outsiders, even in key aspects, especially if they are actively involved.
@captainsafia , “Che, do you want to open the project code?”

Participation in other people's projects


If your goal is to understand how to interact with others and how open source works, consider participating in an existing project that you use and love. Your participation may be such simple things as typos and documentation updates.

If you do not understand how to start participating in someone else's project, check out our guide How to participate in an open source project .

Starting your own open source project


There is no perfect moment to open the source of your work. You can open them at the idea stage, in the process of work, or after several years of closure.

In general, you can open source when you feel confident enough to show your work to strangers and get their feedback.

Each project, regardless of the stage at which you decided to open the source, should have the following documentation:


They will help you convey your expectations, accept the changes of other participants, and protect the legitimate rights of all co-authors, including yourself. This greatly increases the likelihood of a positive experience.

If your project is on a github and you place these files in the root category with recommended names, the github will recognize them and will automatically display them to your readers.

License Choice


An open source license ensures that others can use, copy, modify and make changes to your project without any consequences. It also protects you from unpleasant legal situations. You must enable the license when starting an open source project.

Legal work is not easy. But there is good news: you can copy an existing license and place it in your repository, protecting your hard work in one minute.

MIT , Apache 2.0 , and GPLv3 are the most popular licenses, but there are other options to choose from.

When you create a new project on Github, you are given a choice of several licenses. By choosing an open source license, you will make your project open.

Choose a license

If you have other questions or concerns regarding the legal aspects of open source, we have described them here .

Compilation of README


The README file (“read me”) not only explains how to use your project, but also explains why it is important and what users can do with it.

Try to answer the following questions in README:

  • What does this project do?
  • How is this project useful?
  • How can I start working with him?
  • Where can I get help if needed?

You can specify in README: how to participate in your project, what are its goals, talk about the license and authorship. If you do not plan to accept the improvements of other people, or he is not yet ready to run - just write about it.
avatarGood documentation means more users, fewer requests for help, and more collaborators. (...) Remember that your users are not you. These may be people with experience - very different from yours.
@tracymakes , “Write so your words are read (video)”

Sometimes people postpone writing README because they feel that the project is not completed, or do not want to accept other people's improvements. But this is just a good reason to write about it.

For inspiration, you can read the “Make README” guide or README Template .

When you add the README file to the root directory of the project, the github automatically displays it on the repository main page.

Writing a guide for participants


The CONTRIBUTING file tells your audience how to become a member of your project. For instance:


Besides the technical details, the CONTRIBUTING file is a good place to state your expectations regarding other people's participation. For instance:

  • What kind of participation are you waiting for?
  • Your plans and vision for the development of the project
  • How participants can (and cannot) contact you

Your warm friendly tone and specific proposals for participation, such as writing documentation or creating a site, can be of great importance for attracting newcomers to work on a project.

For example, Active Admin begins its participation guide with these words:
First of all, we want to thank you for considering participating in the development of Active Admin. It is people like you who make Active Admin a great tool.

In the early stages of a project, your CONTRIBUTING file can be simple. You should always explain how to report errors and fill out questions, as well as describe the technical requirements for editing members (for example, tests).

Over time, you can supplement it with answers to frequently asked questions. Because of this, fewer people will ask you the same thing over and over.

To make it easier to compile a CONTRIBUTING file, check out @ nayafia's collaboration guide template ormozilla's "How to compile the file CONTRIBUTING.md" .

Link to the CONTRIBUTING file inside the README, so more people will see it. If you place the CONTRIBUTING.md file in the root of your project , then the github will automatically refer to it when someone opens a new question (issue) or adds an edit to the project (pull request).

collaboration guide

Development of a code of conduct


avatarWe all faced unpleasant situations when the project owner rudely explained something or users asked basic questions. (...) A code of conduct becomes a document that is easy to refer to and that says that your team takes a constructive dialogue very seriously.
@mlynch , Making open source a happier place

As a result, the code of conduct sets the basic rules of conduct for the participants in your project. This is especially important if you are launching a project for a company or community. A code of conduct helps to establish healthy, constructive behavior in the community, which reduces stress for you as the person responsible for the project.

See more details: Code of Conduct - Guide .

In addition to describing how you want participants to behave, the code of conduct also explains to whom and when it applies, and what will happen if it is violated.

By analogy with the license, you do not have to write the code yourself, but you can copy one of the existing options. Member agreement is used inOver 40,000 open source projects including Kubernetes, Rails, and Swift. Whatever code you use, you should be prepared to apply it if necessary.

Put the CODE_OF_CONDUCT.md file in the root of your project, so it will be easier to find and link to it, for example, from README.

Naming and branding your project


Branding is not only a catchy logo and a memorable name, but also how you talk about your project and who your message reaches.

Choosing the right name


Choose a name that is easy to remember and, ideally, gives an idea of ​​the essence of the project. For instance:


If your project is an addition to an existing project, then use its name as a prefix, this will help to understand what your project is doing. For example, node-fetch brings `window.fetch` to Node.js).

Opt for clarity. Puns can be fun, but think of people from other cultures or with different experiences than yours who might not understand the joke. Your potential users may be employees of companies that will talk to your superiors about your project. Do not make them blush at the same time.

Name conflict


Check for open source projects of the same name , especially if you use the same language or ecosystem. If your name matches a popular existing project, you can confuse your audience.

If you plan to start a website, twitter or any publication platform, make sure that the name you need is free there. And it’s better to reserve these names now for peace of mind, even if you do not plan to use them yet.

Make sure that you do not infringe on the trademark of any company. In the future, she will be able to ask you to close the project or even sue. This is an unjustified risk.

You can check the brand conflict on the global WIPO brand database. If you are doing the project on behalf of the company, then the legal department can help you with this .

Finally, do a quick Google search on the name of your project. Will people be able to easily find your project on it? Or maybe something undesirable appears on this request?

The way you write (and code) also affects your brand!


Throughout the life of the project, you will write a lot: README, guides, community documents, answers to questions, perhaps even newsletters and mailing lists.

Whether it’s official documentation or a regular message, your writing style is part of the project’s brand. Think about the light in which you look in front of the audience and whether you have chosen the right tone.
avatar , , . , , , , .
@janl, CouchDB, « Open Source»

A kind and polite language will create a pleasant atmosphere for new participants. Also, keep an eye on the simplicity of presentation, since for many readers English may not be native.

Not only the words that you write, but also the style of the code can become part of the brand of your project. Angular and jQuery are two sample projects with rigorous styles and recommendations.

There is no need to write a style guide when you are just starting out, and in any case you will probably want to include different styles in your project. But you must understand in advance that your writing and code style will attract some people and push others away. The early stages of the project are an opportunity to create a precedent from which the project will grow in the form you want.

Checklist before starting


Are you ready to open your project? Here is a checklist to help you. When you have checked all the items, click "publish" and praise yourself.

Documentation


  • There is an open source LICENSE file in the project
  • The project has basic documentation (README, CONTRIBUTING, CODE_OF_CONDUCT)
  • The name is easy to remember, gives an idea of ​​the essence of the project, does not conflict with existing projects and does not encroach on trademarks.
  • The list of issues is current, well organized, and labeled.

The code


  • The project uses agreed code conventions and friendly names of functions / methods / variables
  • The code is clearly commented on, intentions and special cases are documented.
  • Nowhere is there sensitive data such as passwords or other non-public information - in the history of revisions, issues (issues) and requests for revisions (pull requests).

People


If you are a private individual:

  • You talked to the legal department and / or understood your company's intellectual property rules and open source policies (if you are employed somewhere)

If you are a legal entity:

  • You talked to the legal department
  • Do you have a marketing plan for launching and promoting a project?
  • Someone has been appointed responsible for interacting with the community: answering questions, checking pull requests and attaching them to the project
  • At least two people have administrative access to the project.

You did it!


Congratulations on opening the source code for your first project! Regardless of the result, working in full view of people is a gift for the community. Each commit, comment, and revision request is an opportunity to learn and grow for you and others.

More articles:


All Articles