Skip to main content

Open Source Projects

Every project is unique but there is often a similar organizational structure. Understanding of terms and roles will help you get quickly oriented to any new project.

A typical open source project has the following types of people:

  • Author: The person/s or organization that created the project
  • Owner: The person/s who has administrative ownership over the organization or repository (not always the same as the original author)
  • Maintainers: Contributors who are responsible for driving the vision and managing the organizational aspects of the project (They may also be authors or owners of the project.)
  • Contributors: Everyone who has contributed something back to the project
  • Community Members: People who use the project. They might be active in conversations or express their opinion on the project’s direction Bigger projects may also have subcommittees or working groups focused on different tasks, such as tooling, triage, community moderation, and event organizing. Look on a project’s website for a “team” page, or in the repository for governance documentation, to find this information.

A project also has documentation. These files are usually listed in the top level of a repository.

  • LICENSE: By definition, every open source project must have an open source license. If the project does not have a license, it is not open source.
  • README: The README is the instruction manual that welcomes new community members to the project. It explains why the project is useful and how to get started.
  • CONTRIBUTING: Whereas READMEs help people use the project, contributing docs help people contribute to the project. It explains what types of contributions are needed and how the process works. While not every project has a CONTRIBUTING file, its presence signals that this is a welcoming project to contribute to.
  • CODE_OF_CONDUCT: The code of conduct sets ground rules for participants’ behavior associated and helps to facilitate a friendly, welcoming environment. While not every project has a CODE_OF_CONDUCT file, its presence signals that this is a welcoming project to contribute to. Other documentation: There might be additional documentation, such as tutorials, walkthroughs, or governance policies, especially on bigger projects.

Finally, open source projects use the following tools to organize discussion. Reading through the archives will give you a good picture of how the community thinks and works.

  • Issue tracker: Where people discuss issues related to the project.
  • Pull requests: Where people discuss and review changes that are in progress.
  • Discussion forums or mailing lists: Some projects may use these channels for conversational topics (for example, “How do I…“ or “What do you think about…“ instead of bug reports or feature requests). Others use the issue tracker for all conversations.
  • Synchronous chat channel: Some projects use chat channels (such as Slack or IRC) for casual conversation, collaboration, and quick exchanges.

Writing a README​

READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it.

In your README, try to answer the following questions:

  • What does this project do?
  • Why is this project useful?
  • How do I get started?
  • Where can I get more help, if I need it? You can use your README to answer other questions, like how you handle contributions, what the goals of the project are, and information about licenses and attribution. If you don’t want to accept contributions, or your project is not yet ready for production, write this information down.

Sometimes, people avoid writing a README because they feel like the project is unfinished, or they don’t want contributions. These are all very good reasons to write one.

For more inspiration, try using @dguo’s “Make a README” guide or @PurpleBooth’s README template to write a complete README.

When you include a README file in the root directory, GitHub will automatically display it on the repository homepage.

Writing your contributing guidelines​

A CONTRIBUTING file tells your audience how to participate in your project. For example, you might include information on:

  • How to file a bug report (try using issue and pull request templates)
  • How to suggest a new feature
  • How to set up your environment and run tests

In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions, such as:

  • The types of contributions you’re looking for
  • Your roadmap or vision for the project
  • How contributors should (or should not) get in touch with you Using a warm, friendly tone and offering specific suggestions for contributions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate.