Skip to main content

Contribution policy

Code contributions

If you'd like to fix bugs or add a new feature to MWF (Microsoft Web Framework), please consult the MWF design and development policy.

Before any contribution can be accepted and be part of the project, it needs to be reviewed by existing collaborators in accordance to the guidelines established by the MWF design and development policy.

Becoming a collaborator

By becoming a collaborator, contributors can have even more impact on the project. They can help other contributors by reviewing their contributions, triage issues, and take an even bigger part in shaping the project's future. MWF is always looking for people who are interested in becoming collaborators. If you're interested, make sure you familiarize yourself with the MWF design and development policy.

Guiding principles

The fundamental goal of MWF brings together a cohesive design vision across all of our web properties. We provide a centralized location for designers, developers, and partners to access our design philosophy, UI components and engineering resources necessary for a current, reliable, and stable framework.

Contributors to MWF work in concert with one another on behalf of the community of users who build their applications and businesses with MWF. Accordingly, contributors must demonstrate an ongoing commitment, not only to the project, but to the stability and vitality of the community as a whole.

It is vital that users trust the contributors to have their best interests in mind while making decisions affecting the overall direction of MWF. This means having defined guidelines, a clear roadmap, and a predictable release schedule.

Adoption of new capabilities and features within MWF must be carefully balanced by the expressed needs of the users and the community. Change just for the sake of change must be avoided and a guaranteed long term support policy must be established.

In order to best serve the MWF community as a whole, the development, release, and issue management processes must reflect these guiding principles.

Contributing

Collaborators

MWF is maintained by the MWF design team. The Design & Technical Steering Committee (DTSC) membership consists of key Collaborators who have demonstrated both technical expertise critical to the ongoing maintenance and evolution of the project and a long term commitment to driving the project and community forward.

Individuals can be nominated as collaborators by DTSC members. Once the nomination is approved by the DTSC, the invitation to become a collaborator is extended to the individual. Assuming the individual accepts the invitation and agrees to the terms of DCO (Developer Certificate of Origin) they are granted commit-access to the project.

Nominations for collaborator status happen through the typical DTSC decision making process. That is, to nominate one or more collaborators, DTSC then moves to interview the nominee's. The nominee is approved or rejected following the same consensus seeking process for new MWF design team members.

Individuals can self-petition the DTSC for collaborator status by submitting an written request to be put on the DTSC meeting agenda. In order to be considered however, such self-nominations must be sponsored by an existing DTSC member, after which it follows the same process as above. To sponsor a nomination, the DTSC member must indicate consent.

Collaborators can be nominated to become members of the DTSC following the same nomination and approval model. However, collaborators cannot nominate themselves for DTSC membership. An individual cannot be nominated and accepted into the DTSC without first having been nominated and accepted as a collaborator.

Accepting modifications through a consensus seeking process

A "contribution" to MWF is any work that is voluntarily submitted to the project. These include not only source code in the form of bug fixes, code improvements, new functions, etc..., but contributions to documentation, design etc..., that are intended for the overall improvement of the project.

Contributions to the project are made on a collaborative basis. Any individual with a VSO account and permissions may propose a contribution by submitting a pull request (PR). Like the DTSC governance, acceptance of contributions (a.k.a. "landing a pull request") into MWF follows the consensus seeking decision making model.

All pull requests submitted by individuals who are not collaborators must be signed-off on by an existing collaborator before the PR can be landed. The sponsoring collaborator becomes responsible for the PR. Pull requests from an existing collaborator must be signed-off on by at least one other collaborator.

Before any pull Request is landed, sufficient time should be given to receive input from other collaborators with sufficient expertise to evaluate the changes. Specifically, at least 48 hours during the typical working week and 72 hours over weekends should be given to account for international time differences and work schedules. Trivial pull requests may be landed after a shorter delay.

If it becomes apparent that the changes proposed by a given pull request: (a) have significant impact on the project as a whole; (b) are inherently controversial; or (c) have failed to reach consensus amongst collaborators, the pull request can be elevated for review by attaching a specific tag to the PR ("MWF-DTSC"). Pull requests that have been flagged for DTSC must not be landed until the DTSC has had sufficient opportunity to review the issue and render a decision.

Specific collaborators or working groups can be requested to review any PR by including their user alias into the PR.

Collaborators sign-off on a pull request by explicitly stating their approval in the PR. If a collaborator is unsure about the modification or is not prepared to take full responsibility for the change, they should defer to another collaborator.

Exception to this process is allowed for high-priority changes that address security vulnerabilities. A shorter review period and modified sign-off process may be necessary depending on the nature of the change and severity of the issue. It is recommended that the DTSC establish a security working group of collaborators with recognized security expertise that can be tasked with reviewing security related pull requests and determining an appropriate review process.

All pull requests that either fix bugs or introduce new functionality require at least one test case demonstrating the defect or validating the intended functionality. For bug fixes, the test should fail before the change, and pass after the change. In exceptional cases, such as UI/UX design changes, environments or failure modes that are difficult to reproduce, a detailed description of how to verify the fix may be accepted in lieu of a specific test.

Pull requests for changes intended to improve performance require a benchmark demonstrating the performance impact. The benchmark should demonstrate improved performance after the change is applied.

Release-related commits and error corrections

When cutting a new release, it is typically necessary to commit a few specific changes to the repository. These include tasks like updating the release notes and incrementing the current version number.

It's also possible for errors to come up in the basic management of the project repository (caused either by simple human error or bugs in the tooling used to manage the project). Correction of such errors may require additional changes to be landed.

Such changes can be landed after a significantly shorter review period if the changes are strictly targeted at repairing the current state of the repository or cutting a new release. Effort should still be made to solicit review of such changes in advance of landing them.

Landing pull requests

When landing a pull request, a collaborator must modify the original commit message to include the following additional meta information regarding the change process:

  • A CHANGELOG.md entry including task or bug # in the PR with user understood description for the change.
  • Inclusion for generated HTML/CSS file to validate both pre-compiled source and post-compiled.
  • PR Approval by 1 DTSC Engineer, and at least 2 collaborators.
  • Visual approval by 1 DTSC designer.
  • Functional approval by 1 DTSC engineer who has pulled down the branch, compiled, reviewed and approved the changes.

Long term support working group roadmap

The LTS WG is expected to establish a regular and predictable cadence of LTS Releases. To this end, the LTS WG must maintain and regularly publish a clear roadmap that outlines the priorities and milestones for upcoming LTS releases. The goal of the roadmap is to help guide the project's evolution as opposed to constraining it.

Issues workflow

The tracking and management of issues is still an open discussion.

Stability policy

The most important consideration in every code change is the impact it will have, positive or negative, on the ecosystem (components, modules, and applications). To this end, all collaborators must work collectively to ensure that changes do not needlessly break backwards compatibility, introduce performance or functional regressions, or negatively impact the usability of MWF on any of the partners officially targeted for support.

The DTSC is responsible for determining the list of supported partners.

Working groups

Working groups are autonomous groups of collaborators chartered by the DTSC to oversee specific aspects of the project. Working groups can be formed at any time but must be ratified by the TSC.

Every working group has a charter that details its area of responsibility. Once approved by the DTSC, the working group becomes solely responsible for items detailed in that charter.

When applicable, the charter should indicate the conditions under which the working group's activity can be considered to be complete and the WG can be dissolved. A working group can, at any time, request that the DTSC dissolve the working group by opening an issue requesting dissolution.

The DTSC may revoke the working groups charter at any time following the decision making process defined in the DTSC charter.

Proposals to create a new working group should be made either by opening an issue with the draft charter for the new working group, then putting that on the DTSC agenda.

Developer's Certificate of Origin 1.0

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.