Skip to content

Latest commit

 

History

History
175 lines (111 loc) · 9.89 KB

CONTRIBUTING.md

File metadata and controls

175 lines (111 loc) · 9.89 KB

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

Issues

Issues are very valuable to this project.

  • Ideas are a valuable source of contributions others can make
  • Problems show where this project is lacking
  • With a question, you show where contributors can improve the user experience

When you create a new issue, you need to choose the respective template and it'll guide you through collecting and providing the information needed.

If you find an issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help indicate to our maintainers that a particular problem is affecting more than just the reporter.

Pull Requests

PRs are always welcome and can be a quick way to get your fix or improvement slated for the next release.

Prerequisites

To add a code contribution to our project, you will need:

  1. A bug or feature that you want to work on.
  2. A development machine with either Windows, Mac or Linux operating systems
  3. A Github Account
  4. Git installed and configured
  5. Node v14 or higher installed. If you are in Mac or Linux, you can use nvm or n to help installing and managing node versions
  6. Yarn v1 installed
  7. An editor. VS Code is a good and free editor you can use

Get Started

First, you will need to set up the project on your machine. For that, follow these steps:

  1. Fork the repository to your own Github account
  2. Clone the project to your development machine
  3. Go to the folder where the project was cloned and install the dependencies by running the command yarn install
  4. Run unit tests to make sure everything is working by running the command yarn test
  5. If tests are successfull, follow the steps in the next section to start creating your changes

Creating and submitting your changes

  1. Create a branch locally with a succint name that is prefixed with either fix_ for bug fixes, feat_ for new features and chore_ for everything else

    • Examples: fix_fetch_orders_response, feat_add_bag_client, chore_remove_unnecessary_module.

  2. When creating the code, make sure it follows the coding guidelines

  3. If you need to test your changes in an application, follow these steps:

    1. Run the command yarn dev:link from the root of the project. The script will build the packages exactly as the pipeline does when it generates a new release and then will perform a yarn link call to make each package available for linking.

    2. From the app you want to test your changes, call yarn link <package> for each package that you want to link (this assumes the application is using yarn as well).

      • If you are using webpack in your application make sure the webpack config contains the option webpackConfig.resolve.symlinks equal to false.

    3. Run the app. If you need to test additional changes while the app is running, you can either run the command yarn build to build all the packages again (slow) or run the command yarn build:watch and then perform your changes. When you save the changes, the changed files will be compiled. Make sure your application does not ignore hot reloading files inside node_modules/@farfetch/* directories for the changes to be picked up.

    4. When you are finished, run the command yarn dev:unlink from the root of the project to unlink the @farfetch packages and call yarn unlink <package> from your application's root folder to unlink the @farfetch packages that were linked in step 2.

  4. When you have finished coding, make sure the following checks are passing:

    • Check unit tests by runnning yarn test
    • Check linting errors by running yarn lint
    • Check type errors by runnning yarn ci:types

  5. Commit changes to the branch by following the conventional commits standard

    • The project is configured to lint the commit message and will raise an error if the message is not well formatted
    • The message should state its intent clearly

  6. Push changes to your fork

  7. Open a PR in our repository targeting the correct branch and follow the PR template so that we can efficiently review the changes

Creating good pull requests

When opening a pull request, consider the following:

Clear description

You should be clear about which problem you're trying to solve with your contribution. For example:

Add a link to code of conduct in README.md

This doesn't tell anything about why it's being done, unlike

Add a link to code of conduct in README.md because users don't always look in the CONTRIBUTING.md

This tells the problem that you have found, and the pull request shows the action you have taken to solve it.

The same principle applies to the commit body.

Good quality

Make sure that the PR you are opening is of a good quality in order to be considered for merging. Here are some points you should pay attention to:

  • The PR template is filled correctly
  • There are no spelling mistakes in the description and code
  • The code contains the adequate amount of unit tests
    • Tests should fail when your non-test code is absent
    • Tests should include reasonable permutations of the target fix/change
  • No warnings are introduced by the changes when running unit tests
  • It does not contain unused or commented code
  • Follow the coding guidelines

Workflow

In this project, there are always two main branches - main and next:

  • main - stable version of packages;
  • next - next major version of packages, containing breaking changes and every feature that exists on the stable version.

Any commit made to main should be replicated (and adapted) on next, to ensure nothing is lost between versions. This replication should be isolated, in order to maintain a clear Git history for the release tags and commits pushed. This means that no rebase should be made on these branches, only on PR branches; ie, main and next never actually "touch" each other (although we can cherry-pick some commits instead of actually duplicating changes).

There is also the v1 branch which points to the now legacy packages @farfetch/blackout-core and @farfetch/[email protected]. If a fix or feature is needed for those packages, use that branch as both the base and target of the PR.

Code review and approval process

Our maintainers look at pull requests on a regular basis, and the process follows some simple steps:

  1. PR gets a minimum of 2 approvals when reviewing
  2. After being reviewed, it is tested by our internal QA team
    1. Applicable to bugfixes and features
  3. After being approved, it is merged

If we request some changes to the PR after review, please add the changes in a new commit to ease reviewing. After the changes are reviewed and the PR is ready to be merged, we may ask you to squash your commits to keep git history clean.

Note that after feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.

Release process

Releases are made once a week in the main branch by our maintainers, regardless of the number of features or fixes. It happens automatically with every commit on the main branch.

To prepare the next release, a new branch is created (by the maintainers), named dev-main-<release-date> (for example dev-main-03-11-21 for a scheduled release on Nov 03, 2021) and every PR should target that same branch if it's to be included in that release. In a way, this mimics GitFlow.

On the other hand, a hotfix is released as soon as it's ready and needs no intermediate branch.

The same process should be used for releases targeting the v1 branch with a similarly named dev-v1-<release-date> branch.

Your First Contribution

Have a look at issues that are labelled "good first issue". These are meant to be a great way to get a smooth start and won’t put you in front of the most complex parts of the system.

Additional resources

Disclaimer

By sending us your contributions, you are agreeing that your contribution is made subject to the terms of our Contributor Ownership Statement