Skip to content

Latest commit

 

History

History
183 lines (114 loc) · 7.63 KB

CONTRIBUTING.md

File metadata and controls

183 lines (114 loc) · 7.63 KB
Raw

Contributing to the Microsoft Graph Toolkit

We strongly encourage community feedback and contributions.

Our foundation

The foundation of the Microsoft Graph Toolkit is simplicity.

A developer should be able to quickly and easily learn to use the component/API.

Simplicity and a low barrier to entry are must-have features of every component and API. If you have any second thoughts about the complexity of a design, it is almost always much better to cut the feature from the current release and spend more time to get the design right for the next release.

You can always add to an API, you cannot ever remove anything from one. If the design does not feel right, and you ship it anyway, you are likely to regret having done so.

Do you have a question?

For general questions and support, please use Stack Overflow where questions should be tagged with microsoft-graph-toolkit

Reporting issues and suggesting new features

Please use GitHub Issues for bug reports and feature request.

We highly recommend you browse existing issues first.

Setting up the project

  • Install nodejs if you don't already have it.
  • We recommend using VS Code as your editor
  • We also recommend installing the recommended extensions (recommended by VS Code once the folder is opened)

Clone the repo and run the following in the terminal/command line/powershell:

npm install
npm start

Creating a new component (quick start)

The best way to get started with a new component is to use our snippets for scaffolding:

Note: The steps below assume you are using Visual Studio Code and you've installed all the recommended extensions.

  1. Chose a name for your component. The component must be prefixed with mgt. For example mgt-component

  2. Create a new folder for your new component under src \ components and name it with the name of your component.

  3. Create a new typescript file in your new folder with the same name. Ex: mgt-component.ts

  4. Open the file and use the mgtnew snippet to scaffold the new component.

    To use a snippet, start typing the name of the snippet (mgtnew) and press tab

  5. Tab through the generated code to set the name of your component.

  6. Add your code!

Contributing

Finding issues you can help with

Looking for something to work on? Issues marked good first issue are a good place to start.

You can also check the help wanted tag to find other issues to help with.

Git workflow

The Microsoft Graph Toolkit uses the GitHub flow where most development happens directly on the master branch. The master branch should always be in a healthy state which is ready for release.

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.

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. Each pull request must be validated by at least two core members before being merged

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

Quality assurance for new features

We encourage developers to follow the following guidance when submitting new features:

  1. Ensure the appropriate tests have been added in the src\test folder. Run the tests and make sure they all pass.
  2. Ensure the code is properly documented following the tsdoc syntax
  3. Update the documentation when necessary
  4. Follow the accessibility guidance for web development

Accessibility Guidelines

New features and components should folow the following accessibility implementation guidelines:

(for ease of use)

  1. Visit the following location: https://accessibilityinsights.io/en/
  2. Install the extension, and test

required:

  • aria-label | string: "Login Button", "Megan Bowen" | - meaningful text should have identifiable labels for screen readers

example (mgt-login):

    <button 
        class="popup-command"
        @click=${this.logout} 
        aria-label="Sign Out">       
        Sign Out
    </button>
  • tab-index/focus | string: "0", "-1" | - components that are interactive or display information should be visibilly navigatable by tab key control. Additional information in the aria label should be displayed when this feature is used.

example (mgt-people):

<mgt-person tabindex="0" ></mgt-person>
mgt-person:focus{
    border-color: blue;
}
  • alt | string: "person icon" | - any <img> tag should contain alt text as well

example (mgt-person):

    <img
        title=${this.personDetails.displayName}
        aria-label=${this.personDetails.displayName}
        alt=${this.personDetails.displayName}
        src=${this.personDetails.image as string}
    />

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.