How Tos

Contributing Guidelines

Want to contribute to this repository? Please read below first:

Issues and Bugs

If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to this repo. Even better you can submit a Pull Request with a fix.

Feature Requests

You can request a new feature by submitting an issue to this repo. Proposed features (with suitable design documentation and reasoning) can be crafted and submitted to this repo as a Pull Request.

Doc Fixes

If you want to help improve the docs, it’s a good idea to let others know what you’re working on to minimize duplication of effort. Comment on an issue to let others know what you’re working on, or create a new issue if your work doesn’t fit within the scope of any of the existing doc fix projects.

Submission Guidelines

Submitting an Issue

Before you submit your issue, search the repository. Maybe your question was already answered.

If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.

Setup

1. Fork the project:

  • Navigate to the main Azure Repos repository page.

  • Click the ellipsis menu (...) near the top right (next to the Clone button).

  • Select Fork.

  • In the dialog:

    • Fork name: You can keep it as bridge or choose a different name.
    • Save fork to project: Select the Azure DevOps Project where you want your fork to be created. This will usually be a project under your own organization or one where you have create repository permissions.
    • Choose whether to fork all branches or just the default (develop).
    • Click Fork.

2. Clone your fork:

# Replace the URL below with the HTTPS URL of YOUR fork


git clone https://dev.azure.com/{Your_Organization_Or_Project_For_Fork}/{Your_Project_For_Fork}/_git/{Your_Fork_Name} bridge
cd bridge

Note: {Your_Organization}, {Your_Project} and {Your_Fork_Name} depend on where you created your fork in Step 1.

3. Add the upstream remote:

  • Once cloned, origin will be your default remote, pointing to your personal fork on Azure Repos.
  • Add a remote named upstream pointing back to the original worldfoodprogramme/bridge repository you forked from.
  • Run the following in your terminal:
git remote add upstream https://dev.azure.com/worldfoodprogramme/Design%20System/_git/bridge
git remote -v

Submitting a Pull Request

1. Check Existing Pull Requests:

Search the worldfoodprogramme/bridge repository’s Pull Requests section for an active or completed PR that relates to your submission. Avoid duplicating effort.

2. Sync Your Fork:

Before starting work, ensure your local master branch and your fork are up-to-date with the original worldfoodprogramme/bridge repository’s develop branch.

# Checkout your local develop branch
git checkout master


# Pull the latest changes from the original repository’s develop branch
git pull upstream develop


# Push the updated develop branch to your fork (optional, but good practice)
git push origin master
3. Create a Branch:

Always work and submit pull requests from a new branch created off the updated develop branch. Do not submit pull requests from the develop branch of your fork.

# Create a new branch based on the up-to-date develop branch
# Replace {YOUR_BRANCH_NAME} with a descriptive name (e.g., feat/update-header)
git checkout -b {YOUR_BRANCH_NAME} develop
4. Develop:
5. Commit Changes:

Commit your changes using a descriptive commit message. If your changes relate to an Azure Boards work item, you can reference it (e.g., Fixes AB#123).

# Example commit
git commit -a -m "feat: Update header with newest designs, fixes AB#123"

Note: The -a option automatically stages files that have been modified or deleted. You may need to use git add <file> for new files first. Refer to guides on writing good commit messages and linking work items in Azure DevOps for more details.

6. Push to Your Fork:

Once ready for feedback from other contributors and maintainers, push your commits to your fork (be sure to run yarn ci-check before pushing, to make sure your code passes linting and unit tests):

$ git push origin { YOUR_BRANCH_NAME }
7. Create the Pull Request in Azure Repos:
  • Navigate to the original worldfoodprogramme/bridge repository in your web browser: https://dev.azure.com/worldfoodprogramme/Design%20System/_git/bridge
  • Go to the Repos > Pull requests section.
  • Azure Repos might display a notification prompting you to create a PR from your recently pushed branch. If so, you can click that.
  • Alternatively, click the New pull request button.
  • Select Source and Target:
    • Source: Choose your fork and the branch you just pushed ({YOUR_BRANCH_NAME}).
    • Target: Ensure it’s the correct branch in the worldfoodprogramme/Design System/_git/bridge repository (usually develop).
  • Details: Write a clear title and a detailed description for your PR, explaining the changes and referencing any relevant issues or work items.
  • Click Create pull request.
8. Review Process:
  • Stay up-to-date with activity in your pull request. Maintainers will review your code, provide feedback, ask questions, or request changes.
  • If you need to make changes based on feedback, simply add new commits to your local branch and push them to origin again (git push origin {YOUR_BRANCH_NAME}). The Pull Request will update automatically.
9. Merging:

Once your PR is approved and passes all required checks (like automated builds and tests defined by branch policies), a maintainer will squash and merge your commits for you.

That’s it! Thank you for your contribution to the Bridge Design System!

Coding Standards

To ensure consistency throughout the source code, keep these rules in mind as you are working:

Style Guide

For a set of basic rules and guidelines for developing React components, see here.

Feel free to edit/write components in your own style but be wary that we may ask you to make changes while reviewing your pull request.

Linting

We enforce some style rules for code in this repository using eslint. You can install a linting addon to a lot of editors and IDEs that will follow our linting rules.

If you decide to not install a linter addon, or cannot, you can run yarn lint to get a report of any style issues. Any issues not fixed will be caught during CI, and will prevent merging.

Commit Message Guidelines

We use commit message guidelines based on the Angular Commit Conventions.

After the commit message has been submitted, it is checked by husky and validate-commit-msg to ensure it is syntactically correct.

Testing

If you add any features to our code, make sure to add tests so that your changes are covered. Tests are written using JEST. You can see how well your code is covered by looking at the .gh-pages/coverage/lcov-report/index.html file after running the coverage command.

Test your changes by running our test commands:

  • Run linting:

    yarn lint

  • Run unit tests:

    yarn test

  • Run both linting and unit tests:

    yarn ci-check

  • Watching unit tests:

    yarn test --watch

On this page