Skip to content

Commit

Permalink
Add new contributing.md (#2528)
Browse files Browse the repository at this point in the history 
* modify contributing.md with new guide

* small update on involved feature instructions

* remove name

* update link

Co-authored-by: jennyf19 <jeferrie@microsoft.com>

---------

Co-authored-by: jennyf19 <jeferrie@microsoft.com>
  • Loading branch information
@kellyyangsong @jennyf19
kellyyangsong and jennyf19 authored Oct 19, 2023
1 parent cbb297a commit 24490b2
Showing 1 changed file with 38 additions and 83 deletions.
121 changes: 38 additions & 83 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,111 +7,66 @@ This document will guide you through the process.
Please visit [https://cla.microsoft.com/](https://cla.microsoft.com/) and sign the Contributor License
Agreement. You only need to do that once. We can not look at your code until you've submitted this request.

## Fork
## Finding an issue to work on

Fork the project [on GitHub](https://github.com/AzureAD/microsoft-identity-web) and check out
your copy.
Over the years we've seen many PRs targeting areas of the code which are not urgent or critical for us to address, or areas which we didn't plan to expand further at the time. In all these cases we had to say no to those PRs and close them. That, obviously, is not a great outcome for us. And it's especially bad for the contributor, as they've spent a lot of effort preparing the change. To resolve this problem, we've decided to separate a bucket of issues, which would be great candidates for community members to contribute to. We mark these issues with the help wanted label. You can find all these issues [here](https://github.com/AzureAD/microsoft-identity-web/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22help%20wanted%22%20label%3A%22good%20first%20issue%22).

Example for Microsoft Identity Web:
With that said, we have additionally marked issues that are good candidates for first-time contributors. Those do not require too much familiarity with the authN/authZ and are more novice-friendly. Those are marked with the good first issue label.

```
$ git clone git@github.com:username/microsoft-identity-web.git
$ cd microsoft-identity-web
$ git remote add upstream git@github.com:AzureAD/microsoft-identity-web.git
```
If you would like to make a contribution to an area not captured [here](https://github.com/AzureAD/microsoft-identity-web/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22help%20wanted%22%20label%3A%22good%20first%20issue%22), first open an issue with a description of the change you would like to make and the problem it solves so it can be discussed before a pull request is submitted.

## Setup, Building and Testing
If you are working on an involved feature, please file a design proposal, more instructions can be found below, under [Before writing code](#before-writing-code).

Please see the [Build & Run](https://github.com/AzureAD/microsoft-identity-web/wiki/build-and-test) wiki page.
## Before writing code

## Decide on which branch to create
We've seen PRs, where customers would solve an issue in a way which either wouldn't fit into the E2E design because of how it's implemented, or it would change the E2E in a way, which is not something we'd like to do. To avoid these situations and potentially save you a lot of time, we encourage customers to discuss the preferred design with the team first. To do so, file a new design proposal issue, link to the issue you'd like to address, and provide detailed information about how you'd like to solve a specific problem.

**Bug fixes for the current stable version need to go to 'master' branch.**
To file a design proposal, look for the relevant issue in the `New issue` page or simply click [proposal for IdWeb](https://github.com/AzureAD/microsoft-identity-web/issues/new?assignees=&labels=design-proposal&projects=&template=design_proposal.md)

If you need to contribute to a different branch, please contact us first (open an issue).
## Identifying scale

All details after this point is standard - make sure your commits have nice messages, and prefer rebase to merge.
If you would like to contribute to one of our repositories, first identify the scale of what you would like to contribute. If it is small (grammar/spelling or a bug fix) feel free to start working on a fix. If you are submitting a feature or substantial code contribution, please discuss it with the team and ensure it follows the product roadmap. You might also read these two blogs posts on contributing code: [Open Source Contribution Etiquette by Miguel de Icaza](http://tirania.org/blog/archive/2010/Dec-31.html) and [Don't "Push" Your Pull Requests by Ilya Grigorik](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/). All code submissions will be rigorously reviewed and tested further by the team, and only those that meet an extremely high bar for both quality and design/roadmap appropriateness will be merged into the source.

In case of doubt, please open an issue in the [issue tracker](https://github.com/AzureAD/microsoft-identity-web/issues).
## Before submitting the pull request

Especially do so if you plan to work on a major change in functionality. Nothing is more
frustrating than seeing your hard work go to waste because your vision
does not align with our goals for the SDK.
Before submitting a pull request, make sure that it checks the following requirements:

## Branch
- You find an existing issue with the "help-wanted" label or discuss with the team to agree on adding a new issue with that label.
- You post a high-level description of how it will be implemented and receive a positive acknowledgement from the team before getting too committed to the approach or investing too much effort in implementing it.
- You add test coverage following existing patterns within the codebase
- Your code matches the existing syntax conventions within the codebase
- Your PR is small, focused, and avoids making unrelated changes

Okay, so you have decided on the proper branch. Create a feature branch
and start hacking:
If your pull request contains any of the below, it's less likely to be merged.

```
$ git checkout -b my-feature-branch
```
- Changes that break backward compatibility
- Changes that are only wanted by one person/company. Changes need to benefit a large enough proportion of developers using our auth libraries.
- Changes that add entirely new feature areas without prior agreement
- Changes that are mostly about refactoring existing code or code style

## Commit
Very large PRs that would take hours to review (remember, we're trying to help lots of people at once). For larger work areas, please discuss with us to find ways of breaking it down into smaller, incremental pieces that can go into separate PRs.

Make sure git knows your name and email address:
## During pull request review

```
$ git config --global user.name "J. Random User"
$ git config --global user.email "j.random.user@example.com"
```
A core contributor will review your pull request and provide feedback. To ensure that there is not a large backlog of inactive PRs, the pull request will be marked as stale after two weeks of no activity. After another four days, it will be closed.

Writing good commit logs is important. A commit log should describe what
changed and why. Follow these guidelines when writing one:
## Submitting a pull request

1. The first line should be 50 characters or less and contain a short
description of the change prefixed with the name of the changed
subsystem (e.g. "net: add localAddress and localPort to Socket").
2. Keep the second line blank.
3. Wrap all other lines at 72 columns.
If you're not sure how to create a pull request, read this article: https://help.github.com/articles/using-pull-requests. Make sure the repository can build and all tests pass. Familiarize yourself with the project workflow and our coding conventions. The coding, style, and general engineering guidelines are published on the Engineering guidelines page.

A good commit log looks like this:
## Tests

```
fix: explaining the commit in one line
- Tests need to be provided for every bug/feature that is completed.
- Tests need to be provided for every bug/feature that is completed.
- Unit tests cover all new aspects of the code.
- Before and after performance and stress tests results are evaluated (no regressions allowed).
- Performance and stress tests are extended as relevant.

Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc etc.
## Feedback

The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
72 characters or so. That way `git log` will show things
nicely even when it is indented.
```
Your pull request will now go through extensive checks by the subject matter experts on our team. Please be patient; we have hundreds of pull requests across all of our repositories. Update your pull request according to feedback until it is approved by one of the team members.

The header line should be meaningful; it is what other people see when they
run `git shortlog` or `git log --oneline`.
## Merging pull requests

Check the output of `git log --oneline files_that_you_changed` to find out
what directories your changes touch.

### Rebase

Use `git rebase` (not `git merge`) to sync your work from time to time.

```
$ git fetch upstream
$ git rebase upstream/v0.1 # or upstream/master
```

### Tests

It's all standard stuff, but please note that you won't be able to run integration tests locally because they connect to a KeyVault to fetch some test users and passwords. The CI will run them for you.

### Push

```
$ git push origin my-feature-branch
```

Go to `https://github.com/username/microsoft-identity-web` and select your feature branch. Click
the 'Pull Request' button and fill out the form.

Pull requests are usually reviewed within a few days. If there are comments
to address, apply your changes in a separate commit and push that to your
feature branch. Post a comment in the pull request afterwards; GitHub does
not send out notifications when you add commits.

[on GitHub]: https://github.com/AzureAD/microsoft-identity-web
[issue tracker]: https://github.com/AzureAD/microsoft-identity-web/issues
When your pull request has had all feedback addressed, it has been signed off by one or more reviewers with commit access, and all checks are green, we will commit it.
We commit pull requests as a single Squash commit unless there are special circumstances. This creates a simpler history than a Merge or Rebase commit. "Special circumstances" are rare, and typically mean that there are a series of cleanly separated changes that will be too hard to understand if squashed together, or for some reason we want to preserve the ability to dissect them.

0 comments on commit 24490b2

Please sign in to comment.