github/msft-calculator
1
0
Fork 0
mirror of https://github.com/Microsoft/calculator.git synced 2025-08-21 05:43:10 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updating Contributing (#431)

Browse source 
Updating Contributing documentation:
* Adding reference to spec repository for feature development
* Adding localization issue template
* Adding clarifications for contributions and PRs
This commit is contained in:
Dave Grochocki 2019-04-09 17:36:36 -07:00 • committed by GitHub
commit 47a2741218
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 156 additions and 109 deletions
Download patch file Download diff file Expand all files Collapse all files

84
docs/NewFeatureProcess.md
View file

@ -1,7 +1,8 @@
# New feature process
## Where do I submit my idea for a new feature?
The easiest way to submit new feature requests is through [Feedback Hub](https://insider.windows.com/en-us/fb/?contextid=130).
The easiest way to submit new feature requests is through
[Feedback Hub](https://insider.windows.com/en-us/fb/?contextid=130).
In Feedback Hub, any Windows user (even if they aren't on GitHub) can upvote suggestions. The
Calculator team reviews these suggestions regularly, and when we're ready to work on an idea we
create [feature pitch issues here on GitHub](https://github.com/Microsoft/calculator/issues?q=is%3Aissue+is%3Aopen+project%3AMicrosoft%2Fcalculator%2F1).
@ -12,73 +13,45 @@ product. The [Feature Tracking board](https://github.com/Microsoft/calculator/pr
all the features we're working on and where they're at in the process.
## Do I need to follow this process? Can I just start coding and submit a PR?
You *do not* need to follow this process for bug fixes, performance improvements, or changes to the
development tools. To contribute these changes, [discuss the proposed change in an issue](https://github.com/Microsoft/calculator/issues/new)
You **do not** need to follow this process for bug fixes, performance improvements, or changes to the
development tools. To contribute these changes,
[discuss the proposed change in an issue](https://github.com/Microsoft/calculator/issues/new)
and then submit a pull request.
You *do* need to follow this process for any change which "users will notice". This applies
You **do** need to follow this process for any change which "users will notice". This applies
especially to new features and major visual changes.
## Step 1: Feature pitch
The feature pitch concisely describes a point of view on the problem the new feature should solve.
It will typically include these sections:
Feature pitches are submitted as issues on GitHub using the
[Feature Request template](https://github.com/Microsoft/calculator/issues/new?assignees=&labels=&template=feature_request.md&title=).
We encourage discussion on open issues, and as discussion progresses we will edit the issue description to refine the
idea until it is ready for review.
* **Problem Statement**: What problem are we trying to solve? Who’s the target audience? Is there a
customer need or pain point we need to remedy? Is there a business goal or metric we are trying
to improve? Do we have a hypothesis we want to prove or disprove?
* **Evidence or User Insights**: Why should we do this? Potential sources of data: Feedback Hub,
other GitHub issues, other anecdotes from listening to customers in person or online, request
from another team, telemetry data, user research, market or competitive research
* **Proposal**: How will the solution/feature help us solve the problem? How will it meet the
target audience’s needs? If there are business goals or metrics, how does this improve them?
* **Goals**: What you want to accomplish with this feature. Typical examples include “User Can
*perform some task*”
* **Non-Goals**: Things we are explicitly not doing or supporting or that are out of scope,
including reasons why.
* **Low-Fidelity Concept**: Show as much of the experience as needed to explain the idea. This
can be as simple as a napkin drawing but can also be a code prototype, a PowerPoint walkthrough,
or a design comp.
The low-fidelity concept should be kept simple at this stage and refined during the pre-production
process.
Feature pitches are submitted as issues on GitHub. We encourage discussion on open issues, and as
discussion progresses we will edit the issue description to refine the idea.
We review pitches regularly, and will approve or close issues based on whether they broadly align with the
[Calculator roadmap](https://github.com/Microsoft/calculator/blob/master/docs/Roadmap.md). Approved pitches are moved
into [pre-production](https://github.com/Microsoft/calculator/projects/1) on the feature tracking board.
## Step 2: Pre-production
In the pre-production phase, we experiment with a variety of ways to address the goals described in
the feature pitch. The output of this phase is a specification which demonstrates how the feature
will work, supported by design renderings and code prototypes as needed. Sometimes we'll learn new
things about a feature proposal during pre-production, and we'll edit or close the original pitch.
For most features, the output of this phase is a specification which describes how the feature will work, supported by
design renderings and code prototypes as needed. The original issue will continue to track the overall progress of the
feature, but we will create and iterate on spec documentation in the
[Calculator Spec repo](https://github.com/Microsoft/calculator-specs). Sometimes we'll learn new things about a feature
proposal during pre-production, and we'll edit or close the original pitch.
We welcome community participation in the pre-production process. The GitHub issue will be the
primary place to share progress updates.
The best ideas often come from trying many ideas during the pre-production phase. To enable rapid
We welcome community participation throughout pre-production. The best ideas often come from trying many ideas during
the pre-production phase. To enable rapid
experimentation, we encourage developing and sharing rough ideas—maybe even with pencil and
paper—before making designs pixel-perfect or making code robust and maintainable.
### Spec review
Once there is a high-fidelity design which addresses the goals described in the original pitch, the
Microsoft product team will review the prototype and ensure all items on this checklist are
addressed:
- [ ] Is there a high-fidelity design which gives reviewers a clear idea of how the feature will
look and function when implemented?
- [ ] Has the plan been shared with the community (documented on the wiki and updates posted in the
original issue) and have others been given an opportunity to provide suggestions?
- [ ] Are [Fluent design principles](https://docs.microsoft.com/en-us/windows/uwp/design/fluent-design-system/)
followed? If we do something which deviates from the guidelines, do we have a good reason?
- [ ] Does the design include provisions for [all users](https://docs.microsoft.com/en-us/windows/uwp/design/accessibility/designing-inclusive-software)
and [all cultures](https://docs.microsoft.com/en-us/windows/uwp/design/globalizing/guidelines-and-checklist-for-globalizing-your-app)?
- [ ] Is it technically feasible to build this feature? Take a look at the "before committing"
checklist below and identify any issues which are likely to be blockers.
After the [spec review](https://github.com/Microsoft/calculator-specs#spec-review) is completed, we will move the issue
into [production](https://github.com/Microsoft/calculator/projects/1) on the feature tracking board. In _some_ cases,
all of the details of an idea can be captured concisely in original feature pitch. When that happens, we may move ideas
directly into production.
## Step 3: Production
A feature can be implemented by the original proposer, a Microsoft team member, or by other
community members. Code contributions and testing help are greatly appreciated. Please let us know
in the issue comments if you're actively working on a feature so we can ensure it's assigned to
you.
A feature can be implemented by the original submitter, a Microsoft team member, or by other
community members. Code contributions and testing help are greatly appreciated. Please let everyone know if you're
actively working on a feature to help avoid duplicated efforts from others.
You might be able to reuse code written during the prototype process, although there will typically
be more work required to make the solution robust. Once the code is ready, you can begin
@ -122,7 +95,8 @@ new features, the Microsoft team considers at least these items:
- [ ] Run the perf tests to measure any increase in startup time. Move work out of the startup
path if possible.
- [ ] If the change adds additional logging:
- [ ] All logging should use [TraceLogging](https://docs.microsoft.com/en-us/windows/desktop/tracelogging/trace-logging-about).
- [ ] All logging should use
[TraceLogging](https://docs.microsoft.com/en-us/windows/desktop/tracelogging/trace-logging-about).
- [ ] Unnecessary log events should be removed, or configured so that they are collected only when
needed to debug issues or measure feature usage.
- [ ] If the change reads user data from files or app settings: