Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update CONTRIBUTING.md #1715

Merged
merged 5 commits into from
Mar 19, 2021
Merged

Update CONTRIBUTING.md #1715

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b922b6d
Update CONTRIBUTING.md
michaelhaxhiu Mar 11, 2021
9c12f32
Update CONTRIBUTING.md
michaelhaxhiu Mar 15, 2021
dfd836d
Update CONTRIBUTING.md
michaelhaxhiu Mar 15, 2021
6e701b6
Update CONTRIBUTING.md
michaelhaxhiu Mar 16, 2021
3795e64
Update CONTRIBUTING.md
michaelhaxhiu Mar 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 57 additions & 29 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,32 +2,61 @@
Welcome! Thanks for checking out Expensify.cash and for taking the time to contribute!

## Getting Started
This guide is specifically for external contributors. For a general overview of the repo, check out our README located [here](https://github.com/Expensify/Expensify.cash/blob/master/README.md). The part of the README to pay particular attention to is how to [run the app](https://github.com/Expensify/Expensify.cash#local-development) locally using our production API.
michaelhaxhiu marked this conversation as resolved.
Show resolved Hide resolved
If you would like to become an Expensify.cash contributor, the first step is to read this document in it's entirety. The second step is to review the README guidelines [here](https://github.com/Expensify/Expensify.cash/blob/master/README.md) for a general overview of the code repository (i.e. how to run the app locally, testing, storage, etc). Please read both documents before asking questions, as it may be covered within the documentation.

#### Test Accounts
You can create as many accounts as needed in order to test your changes directly from [expensify.cash](https://expensify.cash/). An initial account can be created when logging in for the first time and additional accounts can be invited by entering a valid email or phone in the "Find or start a chat" input then tapping the avatar.
michaelhaxhiu marked this conversation as resolved.
Show resolved Hide resolved
You can create as many accounts as needed in order to test your changes directly from [expensify.cash](https://expensify.cash/). An initial account can be created when logging in for the first time, and additional accounts can be invited by entering a valid email or phone in the "Find or start a chat" input then tapping the avatar.

## Code of Conduct
This project and everyone participating in it is governed by the Expensify [Code of Conduct](https://github.com/Expensify/Expensify.cash/blob/master/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [contributors@expensify.com](mailto:contributors@expensify.com).

## Asking Questions
The best way to ask questions is to join our #expensify-contributors Slack channel. To request an invite to the channel, just email contributors@expensify.com with the subject "Slack Channel Invite" and we'll send you an invite! Please do not create issues to ask questions.
If you have any general questions, please ask in the #expensify-contributors Slack channel. To request an invite to the channel, just email contributors@expensify.com with the subject `Slack Channel Invite` and we'll send you an invite! The Expensify team will not be able to respond to direct messages in Slack.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should still clarify that GH issues shouldn't be created for the sole purpose of asking questions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm I don't agree because I think we start opening the path to listing all ways to not ask a question if we do this type of approach. Right now I think it's really clear how/when to ask questions, and if we see someone violate that rule we just treat it like our manifesto (point them to the Contributing.md or Readme.md files, and ask them to re-read it).

I feel like listing it out is too exhaustive and specific - like we wouldn't want to get caught up saying "don't ask questions by... making new GH issues, messaging us in Upwork, emailing contributors@expensify.com, posting on the community, reaching out to concierge, etc"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we try out this suggestion, and circle back to update this copy if it's still generating issues to make the update you are proposing? I'm really hoping to keep brevity here so people actually read this guide 🤞 (but hey, time will tell if these edits actually help lol)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that works! We originally included it there since it is common for GH issues to be used to ask questions in open-source repositories, but I agree we can always re-add it if it actually becomes a problem

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since it is common for GH issues to be used to ask questions in open-source repositories

This argument is the first one I'll remember if contributors continue to do this in the future (I've never been an external contributor of another project so I didn't know this!). Let me know if our contributors keep doing this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably fine to take out, but I agree that we don't want people creating GH issues to ask questions.


If you are hired for an Upwork job and have any job-specific questions, please ask in the GitHub issue or pull request. This will ensure that the person addressing your question has as much context as possible.

## Reporting Vulnerabilities
If you've found a vulnerability, please email security@expensify.com with the subject `Vulnerability Report` instead of creating an issue.

## Filing Issues
If you'd like to create a new issue, please first make sure the issue does not exist in the [issue list](https://github.com/Expensify/Expensify.cash/issues). When creating a new issue, please include all the required information on the issue template.

## Payment for Contributions
We are currently managing payment via Upwork. If you'd like to be paid for your contributions, please apply to fix the issue from our [Upwork issue list](https://www.upwork.com/ab/jobs/search/?q=Expensify%20React%20Native&sort=recency&user_location_match=2). Each issue in this repo will also link out to the associated Upwork job.

## Submitting a Pull Request
michaelhaxhiu marked this conversation as resolved.
Show resolved Hide resolved
#### Proposing a Change
1. **Before writing any code**, please post a proposal of the solution you plan to implement as a comment in the GH issue. This should include a brief technical explanation of the changes you will make.
1. Wait for Expensify to review and provide feedback on the proposal within the GH issue, and assign the GH issue to you. Please do not move forward with creating a Pull Request until your proposal is approved
1. Fork this repository and create a new branch
1. ‼️ **Before you start writing any code** ️‼️, please be aware that we require all commits to be [signed](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/signing-commits). The easiest way to do that is to [generate a new GPG key](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-gpg-key) and [add it to your Github account](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/adding-a-new-gpg-key-to-your-github-account). Once you've done that, you can automatically sign all your commits by adding the following to your `.gitconfig`:
michaelhaxhiu marked this conversation as resolved.
Show resolved Hide resolved
We hire and pay external contributors via Upwork.com. If you'd like to be paid for contributing, please create an Upwork account and apply for a job in the [Upwork issue list](https://www.upwork.com/ab/jobs/search/?q=Expensify%20React%20Native&sort=recency&user_location_match=2). Payment for your contributions will be made no less than 7 days after the pull request is merged to allow for regression testing. We hire one contributor for each Upwork job. New Expensify.cash contributors are limited to working on one job at a time, however experienced contributors may work on numerous jobs simultaneously.

## Finding Expensify.cash Jobs
There are two ways you can find an Expensify.cash job that you can contribute to:

#### Finding a job that Expensify posted
This is the most common scenario for contributors. The Expensify team posts Expensify.cash jobs to the Upwork job list [here](https://www.upwork.com/ab/jobs/search/?q=Expensify%20React%20Native&sort=recency&user_location_match=2). Each job in Upwork has a corresponding GitHub issue, which will include instructions to follow.

#### Proposing a job that Expensify hasn’t posted

In this scenario, it’s possible that you found a bug or enhancement that we haven’t posted to the [Upwork job list](https://www.upwork.com/ab/jobs/search/?q=Expensify%20React%20Native&sort=recency&user_location_match=2) or [Github repository](https://github.com/Expensify/Expensify.cash/issues?q=is%3Aissue). This is an opportunity to propose a job, and (optionally) a solution. If it's a valid job proposal, we will compensate you for the solution and give an additional bonus of $150 for proactively proposing the job. In this case, please take the following steps:

1. Check to ensure an issue does not already exist in the Expensify.cash Issue list or Upwork job list. Please use your best judgement to search for similar titles and issue descriptions.
2. If your bug or enhancement matches an existing issue, please feel free to comment on that GitHub issue with your findings if you think it’ll help solve a problem.
3. If there is no existing issue or Upwork job, create a new GitHub issue in the Expensify.cash repo.
4. Make sure to fill out all the required information fields in the issue template.
5. Optional: If you would like to solve the bug or enhancement that you are proposing, please add a comment on your issue with a solution proposal.
6. Pause on this step until a member of the Expensify team responds on your issue with next steps.

## Working on an Expensify.cash Jobs
*Reminder: For technical guidance please refer to the [README](https://github.com/Expensify/Expensify.cash/blob/master/README.md)*.

#### Express interest for the job on Upwork.com

1. If you are interested in working on a job posted in Upwork, click **Submit a Proposal** in Upwork to express your interest to the Expensify team.

#### Make sure you can reproduce the problem
2. Use your test account(s) to reproduce the problem by following the steps in the GitHub issue.
3. If you cannot reproduce the problem, pause on this step and add a comment to the issue explaining where you are stuck.

#### Propose a solution for the job
4. After you reproduce the issue, make a proposal for your solution and post it as a comment in the corresponding GitHub issue (linked in the Upwork job). Your solution proposal should include a brief technical explanation of the changes you will make.
5. Pause at this step until Expensify provides feedback on your proposal (do not begin coding or creating a pull request yet).
6. If your solution proposal is accepted, Expensify will hire you on Upwork and assign the GitHub issue to you.

#### Begin coding your solution in a pull reuqest
7. When you are ready to start, fork the repository and create a new branch.
8. Before you begin writing any code, please be aware that we require all commits to be [signed](https://docs.github.com/en/github/authenticating-to-github/signing-commits). The easiest way to do that is to [generate a new GPG key](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key) and [add it to your Github account](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-gpg-key-to-your-github-account). Once you've done that, you can automatically sign all your commits by adding the following to your `.gitconfig`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We lost the emphasis here. This step gets missed a lot 🤷

```
[commit]
gpgsign = true
Expand All @@ -38,23 +67,22 @@ We are currently managing payment via Upwork. If you'd like to be paid for your
[gpg]
program = gpg
```
1. [Open a PR](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Be sure to fill in all the required information on the PR template.
1. An Expensify engineer will be automatically assigned to review your PR
1. You will need all checks to pass:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these are still important to highlight, including the CLA link. Is there a reason we removed this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oversight on my part - as I thought we captured the part that was important, and didn't deem CLA stuff as fitting the bill. Apologies 😄, fixing now

1. CLA - You must sign our [Contributor License Agreement](https://github.com/Expensify/Expensify.cash/blob/master/CLA.md) by following the CLA bot instructions that will be posted on your PR
1. Tests - All tests must pass before a merge of a pull request
1. Lint - All code must pass lint checks before a merge of a pull request
9. [Open a pull request](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork), and make sure to fill in the required fields.
10. An Expensify engineer will be assigned to your pull request automatically to review.
11. Provide daily updates until reaching completion of your PR.

#### Testing
Upon submission of a PR, please include a numbered list of explicit testing steps for each platform (Web, Desktop, iOS, and Android) to confirm the fix works as expected and there are no regressions.
michaelhaxhiu marked this conversation as resolved.
Show resolved Hide resolved

#### Review Tips
#### Submit your pull request for final request
13. When you are ready to submit your pull request for final review, make sure the following checks pass:
1. CLA - You must sign our [Contributor License Agreement](https://github.com/Expensify/Expensify.cash/blob/master/CLA.md) by following the CLA bot instructions that will be posted on your PR
2. Tests - All tests must pass before a merge of a pull request
3. Lint - All code must pass lint checks before a merge of a pull request
14. Upon submission of a PR, please include a numbered list of explicit testing steps for each platform (Web, Desktop, iOS, and Android) to confirm the fix works as expected and there are no regressions.

### Getting Attention
- If you have made a change and are ready for another review the best way to get your reviewer's attention is to leave a comment that says "Updated" on the PR itself.
- Please do NOT ping individual reviewers in the Slack channel to get their attention and keep the conversation in GitHub whenever possible.
- Patience is a virtue. Reviews can sometimes take place over the course of several days. If your PR has not been addressed after 3 days please leave a comment on the PR. If the PR goes without a response for another day please let us know via Slack.
#### Timeline expectations and asking for help along the way
- If you have made a change to your pull request and are ready for another review, leave a comment that says "Updated" on the pull request itself.
- Please keep the conversation in GitHub, and do not ping individual reviewers in Slack or Upwork to get their attention.
- Pull Request reviews can sometimes take a few days. If your pull request has not been addressed after four days please let us know via the #expensify-contributors Slack channel.

### JavaScript Style
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coming from https://expensify.slack.com/archives/C011W8BJ9L6/p1615481353152800?thread_ts=1615345614.094600&cid=C011W8BJ9L6, let's keep this section here

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned in Slack, I'd like to see this stuff back in here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, adding back

#### Important note about JavaScript Style
- Read our official [JavaScript and React style guide](STYLE.md). Please refer to our Style Guide before asking for a review.
- We have nothing against Prettier or any other automatic style fixers, but we generally don't use them here at Expensify. Do not use Prettier. The style changes these tools enforce don't always align with the ones we recommend and require in our eslint configs and can result in uncessary changes for our reviewers. Ignoring this advice will ultimately make your changes take longer to review as we will ask you to undo any style changes that are not relating to the important changes you are making.