# CLR.fund Contributing 101

## Communicating effectively
Whether you’re a one-time contributor or trying to join the clr.fund community, working with others is one of the most important skills you’ll develop in open source. 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.

😇 “X doesn’t happen when I do Y”

😢 “X is broken! Please fix it.”

### Do your homework beforehand.

😇 “I’m not sure how to implement X. I checked the help docs and didn’t find any mentions.”

😢 “How do I X?”

### Keep requests short and direct.

😇 “I’d like to write an API tutorial.”

😢 “I was driving down the highway the other day and stopped for gas, and then I had this amazing idea for something we should be doing, but before I explain that, let me show 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.

😇 (as a comment) “@-maintainer Hi there! How should we proceed on this PR?”

😢 (as an email) “Hey there, sorry to bother you over email, but I was wondering if you’ve had a chance to review my PR”

### It’s okay to ask questions (but be patient!).
😇 “Thanks for looking into this error. I followed your suggestions. Here’s the output.”

😢 “Why can’t you fix my problem? Isn’t this your project?”

### Respect community decisions.

😇 “I’m disappointed you can’t support my use case, but as you’ve explained it only affects a minor portion of users, I understand why. Thanks for listening.”

😢 “Why won’t you support my use case? This is unacceptable!”

### Above all, keep it classy.
Open source is made up of collaborators from all over the world. Context gets lost across languages, cultures, geographies, and time zones. In addition, written communication makes it harder to convey a tone or mood. Assume good intentions in these conversations. It’s fine to politely push back on an idea, ask for more context, or further clarify your position. Just try to leave the internet a better place than when you found it.

## Gathering context
Before doing anything, do a quick check to make sure your idea hasn’t been discussed elsewhere. Skim the project’s README, issues (open and closed), Discourse and Discord. 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 can’t find your idea elsewhere, you’re ready to make a move by opening an issue or pull request:

- Issues are like starting a conversation or discussion
- Pull requests are for starting work on a solution
- For lightweight communication, such as a clarifying or how-to question, try asking on Discourse, Discord, Telegram, or other chat channels.

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.

## Opening an issue
You should usually open an issue in the following situations:

- Report an error you can’t solve yourself
- 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.

## Opening a pull request
You should usually open a pull request in the following situations:

- Submit trivial fixes (for example, a typo, a broken link or an obvious error)
- Start work on a contribution that was already asked for, or that you’ve already discussed, in an issue
- A pull request doesn’t have to represent finished work. It’s usually better to open a pull request early on, so others can watch or give feedback on your progress. Just mark it as a “WIP” (Work in Progress) in the subject line. You can always add more commits later.

If the project is on GitHub, here’s how to submit a pull request:

1) Fork the repository and clone it locally. Connect your local to the original “upstream” repository by adding it as a remote. Pull in changes from “upstream” often so that you stay up to date so that when you submit your pull request, merge conflicts will be less likely.
2) Create a branch for your edits.
3) Reference any relevant issues or supporting documentation in your PR (for example, “Closes #37.”)
4) Include screenshots of the before and after if your changes include differences in HTML/CSS. Drag and drop the images into the body of your pull request.
5) Test your changes! Run your changes against any existing tests if they exist and create new ones when needed. Whether tests exist or not, make sure your changes don’t break the existing project.
6) Contribute in the style of the project to the best of your abilities. This may mean using indents, semi-colons or comments differently than you would in your own repository, but makes it easier for the maintainer to merge, others to understand and maintain in the future.

## What happens after you submit a contribution
You did it! Congratulations on becoming an clr.fund contributor. We hope it’s the first of many. After you submit a contribution, one of the following will happen:

#### 😭 You don’t get a response.
Hopefully you checked the project for signs of activity before making a contribution. Even on an active project, however, it’s possible that your contribution won’t get a response.

If you haven’t gotten a response in over a week, it’s fair to politely respond in that same thread, asking someone for a review. If you know the name of the right person to review your contribution, you can @-mention them in that thread.

Don’t reach out to that person privately; remember that public communication is vital to open source projects.

#### 🚧 Someone requests changes to your contribution.
It’s common that you’ll be asked to make changes to your contribution, whether that’s feedback on the scope of your idea, or changes to your code.

When someone requests changes, be responsive. They’ve taken the time to review your contribution. Opening a PR and walking away is bad form. If you don’t know how to make changes, research the problem, then ask for help if you need it.

#### 👎 Your contribution doesn’t get accepted.
Your contribution may or may not be accepted in the end. Hopefully you didn’t put too much work into it already. If you’re not sure why it wasn’t accepted, it’s perfectly reasonable to ask the maintainer for feedback and clarification. Ultimately, however, you’ll need to respect that this is their decision. Don’t argue or get hostile. You’re always welcome to fork and work on your own version if you disagree!

#### 🎉 Your contribution gets accepted.
Hooray! You’ve successfully made an open source contribution!