Skip to content

Instantly share code, notes, and snippets.

@FloorD

FloorD/training.md

Last active April 30, 2018 12:09
Show Gist options
  • Save FloorD/f090e32b0c241946183e32d8ac4cd844 to your computer and use it in GitHub Desktop.
Save FloorD/f090e32b0c241946183e32d8ac4cd844 to your computer and use it in GitHub Desktop.
Download ZIP
Basic understanding of Web Development & Open Source Software
Raw
training.md
  1. Introduction to Web Development
  • glossary
  1. Introduction to Open Source
  • glossary
  1. Introduction to contributing to Open Source
  2. Projects looking for non-code contributions

3. Introduction to Open Source

Have you ever seen a typo on a website, and wished someone would fix it? On an open source project, you can do just that. If you’re a new open source contributor, the process can be intimidating. What if something goes wrong? For anything more than a typo fix, contributing to open source is like walking up to a group of strangers at a party. There are all sorts of ways to get involved with an open source project.

A common misconception about contributing to open source is that you need to contribute code. In fact, it’s often the other parts of a project that are most neglected or overlooked. You’ll do the project a huge favor by offering to pitch in with these types of contributions!

Organize workshops or meetups about the project, like @fzamperin did for NodeSchool
Organize the project’s conference (if they have one)
Help community members find the right conferences and submit proposals for speaking

Do you like to design?

Restructure layouts to improve the project’s usability
Conduct user research to reorganize and refine the project’s navigation or menus, like Drupal suggests
Put together a style guide to help the project have a consistent visual design
Create art for t-shirts or a new logo, like hapi.js’s contributors did

Do you like to write?

Write and improve the project’s documentation
Curate a folder of examples showing how the project is used
Start a newsletter for the project, or curate highlights from the mailing list
Write tutorials for the project, like PyPA’s contributors did
Write a translation for the project’s documentation

Do you like organizing?

Link to duplicate issues, and suggest new issue labels, to keep things organized
Go through open issues and suggest closing old ones, like @nzakas did for ESLint
Ask clarifying questions on recently opened issues to move the discussion forward

Do you like to code?

Find an open issue to tackle, like @dianjin did for Leaflet
Ask if you can help write a new feature
Automate project setup
Improve tooling and testing

Do you like helping people?

Answer questions about the project on e.g., Stack Overflow (like this Postgres example) or Reddit
Answer questions for people on open issues
Help moderate the discussion boards or conversation channels

While “open source” often refers to software, you can collaborate on just about anything. There are books, recipes, lists, and classes that get developed as open source projects.

read the room https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project

Contributing to open source happens at all levels, across projects. You don’t need to overthink what exactly your first contribution will be, or how it will look.

Instead, start by thinking about the projects you already use, or want to use. The projects you’ll actively contribute to are the ones you find yourself coming back to.

Within those projects, whenever you catch yourself thinking that something could be better or different, act on your instinct.

Open source isn’t an exclusive club; it’s made by people just like you. “Open source” is just a fancy term for treating the world’s problems as fixable.

You can also use one of the following resources to help you discover and contribute to new projects: https://github.com/explore/ https://opensourcefriday.com/ http://www.firsttimersonly.com/

Here’s how to get your contribution in the right way. Before you open an issue or pull request, or ask a question in chat, keep these points in mind to help your ideas come across effectively.

Give context. Help others get quickly up to speed. If you’re running into an error, explain what you’re trying to do and how to reproduce it. If you’re suggesting a new idea, explain why you think it’d be useful to the project (not just to you!). Do your homework beforehand. It’s OK not to know things, but show that you tried. Before asking for help, be sure to check a project’s README, documentation, issues (open or closed), mailing list, and search the internet for an answer. People will appreciate when you demonstrate that you’re trying to learn. Keep requests short and direct. Much like sending an email, every contribution, no matter how simple or helpful, requires someone else’s review. Many projects have more incoming requests than people available to help. Be concise. You will increase the chance that someone will be able to help you. Keep all communication public. Although it’s tempting, don’t reach out to maintainers privately unless you need to share sensitive information (such as a security issue or serious conduct violation). When you keep the conversation public, more people can learn and benefit from your exchange. Discussions can be, in themselves, contributions.

It’s okay to ask questions (but be patient!). Everybody was new to the project at some point, and even experienced contributors need to get up to speed when they look at a new project. By the same token, even longtime maintainers are not always familiar with every part of the project. Show them the same patience that you’d want them to show to you.

Respect community decisions. Your ideas may differ from the community’s priorities or vision. They may offer feedback or decide not to pursue your idea. While you should discuss and look for compromise, maintainers have to live with your decision longer than you will. If you disagree with their direction, you can always work on your own fork or start your own project.

You don’t have to spend hours going through everything, but a quick search for a few key terms goes a long way.

If you want to make a substantial contribution, open an issue to ask before working on it. It’s helpful to watch the project for a while (on GitHub, you can click “Watch” to be notified of all conversations), and get to know community members, before doing work that might not get accepted.

You should usually open an issue in the following situations:

Report an error you can’t solve yourself
Discuss a high-level topic or idea (for example, community, vision or policies)
Propose a new feature or other project idea

Tips for communicating on issues:

If you see an open issue that you want to tackle, comment on the issue to let people know you’re on it. That way, people are less likely to duplicate your work.
If an issue was opened a while ago, it’s possible that it’s being addressed somewhere else, or has already been resolved, so comment to ask for confirmation before starting work.
If you opened an issue, but figured out the answer later on your own, comment on the issue to let people know, then close the issue. Even documenting that outcome is a contribution to the project.

4. Projects looking for non-code contributions

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment