Skip to content

Home

Jump to bottom
Gavin Barron edited this page Nov 29, 2023 · 14 revisions

Welcome

Welcome to the Microsoft Graph Toolkit Wiki. These pages are primarily intended for those who wish to contribute to the project by submitting bug reports, suggesting new features, building extensions, commenting on new ideas, or even by submitting pull requests. We love community contributions so please do get involved.

Please refer to the sidebar (on the right) for details on Contributing.

If you are looking for more information on using Microsoft Graph Toolkit, please visit our Documentation and Component Playground!

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Contributing to Microsoft Graph Toolkit

If you are not sure how you can contribute to the toolkit, start with our issues. Issues labeled help wanted are good issues to submit a PR for. Issues labeled good first issue are great candidates to pick up if you are in the code for the first time. If you are contributing significant changes, please discuss with the assignee of the issue first before starting to work on the issue.

Once you are ready to do your first contribution, follow these steps to get setup for contributing code to the Microsoft Graph Toolkit!

For more advanced topic, see the nav bar on the right.

If you have a really big idea, it would be best to raise an issue to discuss the idea before jumping straight to writing code.

Setup the development environment

Before cloning the repository, make sure you've installed the following prerequisites

Required (in this order)

  1. Git (latest version)

  2. Node.js (Node.js 18 is supported)

  3. yarn is used as a package manager, to ensure this works run corepack enable

Recommended

Clone and build the project

  1. Clone the repository and navigate to the project root.

    git clone https://github.com/microsoftgraph/microsoft-graph-toolkit

cd microsoft-graph-toolkit

  2. Install all dependencies

    yarn

  3. Build the project

    yarn build

NOTE it will take few minutes to install all dependencies and build the project

Developing

There are several ways to "run" the project and test your changes. All have pros and cons and you might find using a combination of these as you are developing and testing changes.

1. yarn start 

yarn start

The main start script will spin up a basic web server and open the browser pointing to the index.html in the root of the repo. This script will also start up the typescript compiler in watch mode which will reload the page as you are changing the code.

You can use index.html while developing and this is, for most scenarios, the fastest way to see your changes. However, please DO NOT commit any changes to this file unless you've already discussed this with the maintainers. We'd like to keep the index.html file simple and clean which makes it easier to use for debugging.

2. yarn start:storybook 

> yarn start:storybook

This script will launch storybook, the local version of mgt.dev. It will also watch for any changes to the source files and reload the story as you are working. See Storybook for how to use storybook for development.

3. Running samples

The repository also contains one in-depth sample that makes it easier to developer and test specific features. The react-contoso sample is useful when building components and ensuring full compatibility with the @microsoft/mgt-react package.

cd ./samples/react-contoso
yarn start

Git workflow

The Microsoft Graph Toolkit uses the GitHub flow where most development happens directly on the main branch. The main branch should always be in a healthy state which is ready for release. In general, you will use the main branch as the base for your Pull Requests unless a maintainer has specified a different branch.

If your change is complex, please clean up the branch history before submitting a pull request. You can use git rebase to group your changes into a small number of commits which we can review one at a time.

When completing a pull request, we will generally squash your changes into a single commit. Please let us know if your pull request needs to be merged as separate commits.

Submitting a pull request and participating in code review

Writing a good description for your pull request is crucial to help reviewers and future maintainers understand your change. Make sure to complete the pull request template to avoid delays. More detail is better.

  • Link the issue you're addressing in the pull request. Each pull request must be linked to an issue.
  • Describe why the change is being made and why you've chosen a particular solution.
  • Describe any manual testing you performed to validate your change.
  • Ensure the appropriate documentation has been added and linked to the Pull Request
  • Write stories to demonstrate and help test your changes. The stories will be part of mgt.dev

Please submit one pull request per issue. Large pull requests which have unrelated changes can be difficult to review.

After submitting a pull request, core members of the project will review your code.

Often, multiple iterations will be needed to responding to feedback from reviewers.

Quality assurance for new features

When submitting a new Pull Request, we will be looking for the following items and may ask you to complete them before we can do a full review:

  1. Run yarn build locally to make sure the build will not fail and any autogenerated code has been committed
  2. Write stories to demonstrate and help test your changes. Verify your changes have not broken any existing stories
  3. Test your feature in at least two browsers (Edge + 1 non-Chromium based browser)
  4. Ensure the code is properly documented following the jsdoc syntax. We expect all public APIs to be fully documented
  5. Update the documentation when necessary and link a documentation PR
  6. Follow the accessibility guidance for web development, and please refer to our specific accessibility guidance for component work
  7. If introducing breaking changes, make sure to document those and describe why they are necessary. Keep in mind, any breaking changes will delay your feature until the next major release.
  8. Use conventional commits to describe your changes. The git history on this project is used to automate release generation including version increments and updating the changelog.

Contributing

Resources

Clone this wiki locally