DevWiki/calculator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
parent 7ac750f7e5
commit 47a2741218
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 156 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -6,36 +6,45 @@ labels: ''
assignees: '' assignees: ''
--- ---
<!--Before filing a bug <!--
Before filing a bug
- Ensure the bug reproduces on the latest version of the app. - Ensure the bug reproduces on the latest version of the app.
- Search existing issues and make sure this issue is not already filed.--> - Search existing issues and make sure this issue is not already filed.
-->
**Describe the bug** **Describe the bug**
<!--A clear and concise description of what the bug is.--> <!-- A clear and concise description of what the bug is. -->
**Steps To Reproduce** **Steps To Reproduce**
<!--Steps to reproduce the behavior: <!--
Steps to reproduce the behavior:
1. Go to '...' 1. Go to '...'
2. Click on '....' 2. Click on '....'
3. Scroll down to '....' 3. Scroll down to '....'
4. See error--> 4. See error
-->
**Expected behavior** **Expected behavior**
<!--A clear and concise description of what you expected to happen.--> <!-- A clear and concise description of what you expected to happen. -->
**Screenshots** **Screenshots**
<!--If applicable, add screenshots to help explain your problem.--> <!-- If applicable, add screenshots to help explain your problem. -->
**Device and Application Information (please complete the following information):** **Device and Application Information**
- OS Build: - OS Build:
- Architecture: - Architecture:
- Application Version: - Application Version:
- Region:
<!--Run the following commands in Powershell and copy/paste the output. - Dev Version Installed:
<!--
Run the following commands in Powershell and copy/paste the output.
" - OS Build: $([Environment]::OSVersion.Version)" " - OS Build: $([Environment]::OSVersion.Version)"
" - Architecture: $((Get-AppxPackage -Name Microsoft.WindowsCalculator).Architecture)" " - Architecture: $((Get-AppxPackage -Name Microsoft.WindowsCalculator).Architecture)"
" - Application Version: $((Get-AppxPackage -Name Microsoft.WindowsCalculator).Version)" " - Application Version: $((Get-AppxPackage -Name Microsoft.WindowsCalculator).Version)"
" - Region: $((Get-Culture).Name)"
" - Dev Version Installed: $($null -ne (Get-AppxPackage -Name Microsoft.WindowsCalculator.Dev))"
--> -->
**Additional context** **Additional context**
<!--Add any other context about the problem here.--> <!-- Add any other context about the problem here. -->

42
.github/ISSUE_TEMPLATE/feature_request.md vendored
View File

@ -2,42 +2,42 @@
name: Feature request name: Feature request
about: Propose a new feature in the app about: Propose a new feature in the app
title: '' title: ''
labels: '' labels: 'Enhancement'
assignees: '' assignees: ''
--- ---
<!-- <!--
See https://github.com/Microsoft/calculator/blob/master/docs/NewFeatureProcess.md for suggestions on how to write a good feature pitch. Just want to submit an idea quickly? Try Feedback Hub instead: https://insider.windows.com/en-us/fb/?contextid=130
See https://github.com/Microsoft/calculator/blob/master/docs/NewFeatureProcess.md for
suggestions on how to write a good feature pitch. Just want to submit an idea quickly? Try Feedback
Hub instead: https://insider.windows.com/en-us/fb/?contextid=130
--> -->
**Problem Statement** **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 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?
have a hypothesis we want to prove or disprove? --> -->
**Evidence or User Insights** **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 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
data, user research, market or competitive research --> -->
**Proposal** **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? --> 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** **Goals**
<!-- What you want to accomplish with this feature. Typical examples include <!--
“User Can *perform some task*” --> What you want to accomplish with this feature. Typical examples include
"User Can *perform some task*"
-->
**Non-Goals** **Non-Goals**
<!-- Things we are explicitly not doing or supporting or that are out of scope, including reasons <!--
why. --> Things we are explicitly not doing or supporting or that are out of scope, including reasons why.
-->
**Low-Fidelity Concept** **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 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, or a design comp. Keep it simple at this stage, as it can be refined later during the pre-production stage.
comp. --> -->

54
.github/ISSUE_TEMPLATE/localization_suggestion.md vendored Normal file
View File

@ -0,0 +1,54 @@
---
name: Localization Suggestion
about: Report a problem or suggested change to Calculator's localized content.
title: '[Localization] '
labels: 'Area: World-Readiness'
assignees: ''
---
<!--
PLEASE NOTE:
We cannot _merge_ any suggested localization changes to our localized resources files. These files are automatically generated from an internal localization process. Any suggestion submitted this way will be duplicated into our internal localization system, and then closed here.
Alternatively, you can launch feedback-hub://, click on the "Language Community" tab on the left-side of the app, and follow the steps to submit a localization suggestion that way. (The "Language Community" tab currently will only be visible if your system is running a non-English language).
Before filing a bug
- Ensure the bug reproduces on the latest version of the app.
- Search existing issues and make sure this issue is not already filed.
-->
**Describe the bug**
<!-- A clear and concise description of what the bug is. -->
**Steps To Reproduce**
<!--
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
-->
**Expected behavior**
<!-- A clear and concise description of what you expected to happen. -->
**Screenshots**
<!-- If applicable, add screenshots to help explain your problem. -->
**Device and Application Information**
- OS Build:
- Architecture:
- Application Version:
- Region:
- Dev Version Installed:
<!--
Run the following commands in Powershell and copy/paste the output.
" - OS Build: $([Environment]::OSVersion.Version)"
" - Architecture: $((Get-AppxPackage -Name Microsoft.WindowsCalculator).Architecture)"
" - Application Version: $((Get-AppxPackage -Name Microsoft.WindowsCalculator).Version)"
" - Region: $((Get-Culture).Name)"
" - Dev Version Installed: $($null -ne (Get-AppxPackage -Name Microsoft.WindowsCalculator.Dev))"
-->
**Additional context**
<!-- Add any other context about the problem here. -->

54
CONTRIBUTING.md
View File

@ -3,7 +3,8 @@ The Calculator team encourages community feedback and contributions. Thank you f
making Calculator better! There are several ways you can get involved. making Calculator better! There are several ways you can get involved.
## Reporting issues and suggesting new features ## Reporting issues and suggesting new features
If Calculator is not working properly, please file a report in the [Feedback Hub](https://insider.windows.com/en-us/fb/?contextid=130&newFeedback=True). If Calculator is not working properly, please file a report in the
[Feedback Hub](https://insider.windows.com/en-us/fb/?contextid=130&newFeedback=True).
Feedback Hub reports automatically include diagnostic data, such as the version of Calculator Feedback Hub reports automatically include diagnostic data, such as the version of Calculator
you're using. you're using.
@ -17,21 +18,38 @@ all community interactions must abide by the [Code of Conduct](CODE_OF_CONDUCT.m
## Finding issues you can help with ## Finding issues you can help with
Looking for something to work on? Looking for something to work on?
[Issues marked *good first issue*](https://github.com/Microsoft/calculator/labels/good%20first%20issue) Issues marked [``good first issue``](https://github.com/Microsoft/calculator/labels/good%20first%20issue)
are a good place to start. are a good place to start.
You can also check [the *help wanted* tag](https://github.com/Microsoft/calculator/labels/help%20wanted) You can also check the [``help wanted``](https://github.com/Microsoft/calculator/labels/help%20wanted) tag to find
to find other issues to help with. other issues to help with. If you're interested in working on a fix, leave a comment to let everyone know and to help
avoid duplicated effort from others.
## Contributions we accept ## Contributions we accept
We welcome your contributions to the Calculator project, especially to fix bugs and to make We welcome your contributions to the Calculator project, especially to fix bugs and to make
improvements which address the top issues reported by Calculator users. improvements which address the top issues reported by Calculator users. Some general guidelines:
We have a high bar for new features and changes to the user experience. We prefer to evaluate * **DO** create one pull request per Issue, and ensure that the Issue is linked in the pull request.
*prototypes* to ensure that the design meets users' needs before we start discussing implementation * **DO** follow our [Coding and Style](#style-guidelines) guidelines, and keep code changes as small as possible.
details and reviewing code. We follow a [user-centered process for developing features](docs/NewFeatureProcess.md). * **DO** include corresponding tests whenever possible.
New features need sponsorship from the Calculator team, but we welcome community contributions at * **DO** check for additional occurrences of the same problem in other parts of the codebase before submitting your PR.
many stages of the process. * **DO** [link the issue](https://github.com/blog/957-introducing-issue-mentions) you are addressing in the
pull request.
* **DO** write a good description for your pull request. More detail is better. Describe *why* the change is being
made and *why* you have chosen a particular solution. Describe any manual testing you performed to validate your change.
* **DO NOT** submit a PR unless it is linked to an Issue marked
[`triage approved`](https://github.com/Microsoft/calculator/issues?q=is%3Aissue+is%3Aopen+label%3A%22Triage%3A+Approved%22).
This enables us to have a discussion on the idea before anyone invests time in an implementation.
* **DO NOT** merge multiple changes into one PR unless they have the same root cause.
* **DO NOT** submit pure formatting/typo changes to code that has not been modified otherwise.
We follow a [user-centered process for developing features](docs/NewFeatureProcess.md). New features
need sponsorship from the Calculator team, but we welcome community contributions at many stages of
the process.
> Submitting a pull request for an approved Issue is not a guarantee it will be approved.
> The change must meet our high bar for code quality, architecture, and performance, as well as
> [other requirements](#docs/NewFeatureProcess.md#technical-review).
## Making changes to the code ## Making changes to the code
@ -41,7 +59,8 @@ To learn how to build the code and run tests, follow the instructions in the [RE
### Style guidelines ### Style guidelines
The code in this project uses several different coding styles, depending on the age and history of The code in this project uses several different coding styles, depending on the age and history of
the code. Please attempt to match the style of surrounding code as much as possible. In new the code. Please attempt to match the style of surrounding code as much as possible. In new
components, prefer the patterns described in the [C++ core guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) components, prefer the patterns described in the
[C++ core guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines)
and the [modern C++/WinRT language projections](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/). and the [modern C++/WinRT language projections](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/).
### Testing ### Testing
@ -61,18 +80,9 @@ to group your changes into a small number of commits which we can review one at
When completing a pull request, we will generally squash your changes into a single commit. Please 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. let us know if your pull request needs to be merged as separate commits.
## Submitting a pull request and participating in code review ## Review Process
Writing a good description for your pull request is crucial to help reviewers and future
maintainers understand your change. More detail is better.
- [Link the issue you're addressing in the pull request](https://github.com/blog/957-introducing-issue-mentions).
- 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.
Please submit one pull request per issue. Large pull requests which have unrelated changes can be
difficult to review.
After submitting a pull request, members of the calculator team will review your code. We will After submitting a pull request, members of the calculator team will review your code. We will
assign the request to an appropriate reviewer within two days. Any member of the community may assign the request to an appropriate reviewer. Any member of the community may
participate in the review, but at least one member of the Calculator team will ultimately approve participate in the review, but at least one member of the Calculator team will ultimately approve
the request. the request.

84
docs/NewFeatureProcess.md
View File

@ -1,7 +1,8 @@
# New feature process # New feature process
## Where do I submit my idea for a new feature? ## 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 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 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). 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. 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? ## 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 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) 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. 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. especially to new features and major visual changes.
## Step 1: Feature pitch ## Step 1: Feature pitch
The feature pitch concisely describes a point of view on the problem the new feature should solve. Feature pitches are submitted as issues on GitHub using the
It will typically include these sections: [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 We review pitches regularly, and will approve or close issues based on whether they broadly align with the
customer need or pain point we need to remedy? Is there a business goal or metric we are trying [Calculator roadmap](https://github.com/Microsoft/calculator/blob/master/docs/Roadmap.md). Approved pitches are moved
to improve? Do we have a hypothesis we want to prove or disprove? into [pre-production](https://github.com/Microsoft/calculator/projects/1) on the feature tracking board.
* **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.
## Step 2: Pre-production ## Step 2: Pre-production
In the pre-production phase, we experiment with a variety of ways to address the goals described in For most features, the output of this phase is a specification which describes how the feature will work, supported by
the feature pitch. The output of this phase is a specification which demonstrates how the feature design renderings and code prototypes as needed. The original issue will continue to track the overall progress of the
will work, supported by design renderings and code prototypes as needed. Sometimes we'll learn new feature, but we will create and iterate on spec documentation in the
things about a feature proposal during pre-production, and we'll edit or close the original pitch. [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 We welcome community participation throughout pre-production. The best ideas often come from trying many ideas during
primary place to share progress updates. the pre-production phase. To enable rapid
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&mdash;maybe even with pencil and experimentation, we encourage developing and sharing rough ideas&mdash;maybe even with pencil and
paper&mdash;before making designs pixel-perfect or making code robust and maintainable. paper&mdash;before making designs pixel-perfect or making code robust and maintainable.
### Spec review After the [spec review](https://github.com/Microsoft/calculator-specs#spec-review) is completed, we will move the issue
Once there is a high-fidelity design which addresses the goals described in the original pitch, the into [production](https://github.com/Microsoft/calculator/projects/1) on the feature tracking board. In _some_ cases,
Microsoft product team will review the prototype and ensure all items on this checklist are all of the details of an idea can be captured concisely in original feature pitch. When that happens, we may move ideas
addressed: directly into production.
- [ ] 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.
## Step 3: Production ## Step 3: Production
A feature can be implemented by the original proposer, a Microsoft team member, or by other 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 us know community members. Code contributions and testing help are greatly appreciated. Please let everyone know if you're
in the issue comments if you're actively working on a feature so we can ensure it's assigned to actively working on a feature to help avoid duplicated efforts from others.
you.
You might be able to reuse code written during the prototype process, although there will typically 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 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 - [ ] Run the perf tests to measure any increase in startup time. Move work out of the startup
path if possible. path if possible.
- [ ] If the change adds additional logging: - [ ] 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 - [ ] Unnecessary log events should be removed, or configured so that they are collected only when
needed to debug issues or measure feature usage. needed to debug issues or measure feature usage.
- [ ] If the change reads user data from files or app settings: - [ ] If the change reads user data from files or app settings: