You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Feature/clean up doc structure after mkdocs (microsoft#618)
* flatten backlog-refinement
* flatten structure for agile-development
* flatten structure and fix language nits
* fix wording in tests section
* fix language nits in code reviews
* fix language nits in CI/CD
* fix language nits in data fundamentals and design reviews
* standardize page title capitalization
* language nits for developer experience
* language nits for documentation
* langauge nits in the engineering feedback
* langauge nits ml-fundamentals
* language nits observability
* language nits reliability
* language nits secuirty
* language nits in source control
* fix tip
* fix markdown lint
* fix links from merge
* fix broken links
* move readme to README - so that they act as index pages for each section
* disable link check for problematic link
Co-authored-by: Tess Ferrandez <[email protected]>
and ensure that all rules are followed. This will help ensure consistency in the
70
70
look and feel of the documentation in this repo.
71
71
72
-
You can find information about other linters, general writing guidelines and code review check lists for Markdown in the [Markdown code review recipe](docs/code-reviews/recipes/Markdown.md).
72
+
You can find information about other linters, general writing guidelines and code review check lists for Markdown in the [Markdown code review recipe](docs/code-reviews/recipes/markdown.md).
73
73
74
74
### Contributions and pull requests
75
75
76
76
When creating pull requests, follow guidance similar to the one suggested in
77
-
this repo, as described in the ["Pull Request Template"](docs/code-reviews/pull_request_template.md)
77
+
this repo, as described in the ["Pull Request Template"](docs/code-reviews/pull-request-template/pull-request-template.md)
78
78
section, under "Code Reviews". This includes linking to the work item that
79
79
prompted the pull request.
80
80
81
81
### Merging strategy
82
82
83
83
The preferred merging strategy for this repo is **linear**.
84
-
You can familiarize yourself with [merging strategies](docs/source-control/contributing/merge-strategies.md) described in the Source Control section of this repo.
84
+
You can familiarize yourself with [merging strategies](docs/source-control/merge-strategies.md) described in the Source Control section of this repo.
Our team, CSE (Commercial Software Engineering), works side by side with customers to help them tackle their toughest technical problems both in the cloud and on the edge. We meet customers where they are, work in the languages they use, with the open source frameworks they use, on the operating systems they use. We work with enterprises and start-ups across many industries from financial services to manufacturing. Our work covers a broad spectrum of domains including IoT, machine learning, and high scale compute. Our "super power" is that we work closely with both our customers’ engineering teams and Microsoft’s product engineering teams, developing real-world expertise that we use to help our customers grow their business and help Microsoft improve our products and services.
3
+
Our team, CSE (Commercial Software Engineering), works side by side with customers to help them tackle their toughest technical problems both in the cloud and on the edge. We meet customers where they are, work in the languages they use, with the open source frameworks they use, on the operating systems they use. We work with enterprises and start-ups across many industries from financial services to manufacturing. Our work covers a broad spectrum of domains including IoT, machine learning, and high scale compute. Our "superpower" is that we work closely with both our customers’ engineering teams and Microsoft’s product engineering teams, developing real-world expertise that we can use to help our customers grow their business and help Microsoft improve our products and services.
4
4
5
5
We are very community focused in our work, with one foot in Microsoft and one foot in the open source communities that we help. We make pull requests on open source projects to add support for Microsoft platforms and/or improve existing implementations. We build frameworks and other tools to make it easier for developers to use Microsoft platforms. We source all the ideas for this work by maintaining very deep connections with these communities and the customers and partners that use them.
6
6
7
7
If you like variety, coding in many languages, using any available tech across our industry, digging in with our customers, hack fests, occasional travel, and telling the story of what you’ve done in [blog posts](https://www.microsoft.com/developerblog/) and at conferences, then come talk to us.
8
8
9
-
> You can checkout some of our work on our [Developer Blog](https://www.microsoft.com/developerblog/)
9
+
> You can check out some of our work on our [Developer Blog](https://www.microsoft.com/developerblog/)
Copy file name to clipboardexpand all lines: docs/ENG-FUNDAMENTALS-CHECKLIST.md
+12-12
Original file line number
Diff line number
Diff line change
@@ -10,32 +10,32 @@ This checklist helps to ensure that our projects meet our Engineering Fundamenta
10
10
-[ ] Commit history is consistent and commit messages are informative (what, why).
11
11
-[ ] Consistent branch naming conventions.
12
12
-[ ] Clear documentation of repository structure.
13
-
-[ ] Secrets are not part of the commit history or made public. (see [Credential scanning](continuous-integration/credential-scanning/readme.md))
14
-
-[ ] Public repositories follow the [OSS guidelines](source-control/readme.md#creating-a-new-repository), see `Required files in default branch for public repositories`.
13
+
-[ ] Secrets are not part of the commit history or made public. (see [Credential scanning](continuous-integration/credential-scanning/README.md))
14
+
-[ ] Public repositories follow the [OSS guidelines](source-control/README.md#creating-a-new-repository), see `Required files in default branch for public repositories`.
15
15
16
-
More details on [source control](source-control/readme.md)
16
+
More details on [source control](source-control/README.md)
17
17
18
18
## Work Item Tracking
19
19
20
20
-[ ] All items are tracked in AzDevOps (or similar).
21
21
-[ ] The board is organized (swim lanes, feature tags, technology tags).
22
22
23
-
More details on [backlog management](agile-development/backlog-management/readme.md)
23
+
More details on [backlog management](agile-development/backlog-management/README.md)
24
24
25
25
## Testing
26
26
27
27
-[ ] Unit tests cover the majority of all components (>90% if possible).
28
28
-[ ] Integration tests run to test the solution e2e.
29
29
30
-
More details on [automated testing](automated-testing/readme.md)
30
+
More details on [automated testing](automated-testing/README.md)
31
31
32
32
## CI/CD
33
33
34
34
-[ ] Project runs CI with automated build and test on each PR.
35
35
-[ ] Project uses CD to manage deployments to a replica environment before PRs are merged.
36
36
-[ ] Main branch is always shippable.
37
37
38
-
More details on [continuous integration](continuous-integration/readme.md) and [continuous delivery](continuous-delivery/readme.md)
38
+
More details on [continuous integration](continuous-integration/README.md) and [continuous delivery](continuous-delivery/README.md)
39
39
40
40
## Security
41
41
@@ -56,7 +56,7 @@ More details on [security](security/README.md)
56
56
-[ ][Incoming tracing context](observability/correlation-id.md) is propagated to allow for production issue debugging purposes.
Copy file name to clipboardexpand all lines: docs/SPRINT-STRUCTURE.md
+27-27
Original file line number
Diff line number
Diff line change
@@ -4,71 +4,71 @@ The purpose of this document is to:
4
4
5
5
- Organize content in the playbook for quick reference and discoverability
6
6
- Provide content in a logical structure which reflects the engineering process
7
-
- Extensible hierarchy to allow teams to share deep subjectmatter expertise
7
+
- Extensible hierarchy to allow teams to share deep subject-matter expertise
8
8
9
9
## The first week of a CSE Project
10
10
11
11
### Before starting the project
12
12
13
-
-[ ][Discuss and start writing the Team Agreements](agile-development/team-agreements/readme.md). Update these documents with any process decisions made throughout the project
-[ ][Set up the repository/repositories](source-control/readme.md#creating-a-new-repository)
13
+
-[ ][Discuss and start writing the Team Agreements](agile-development/team-agreements/README.md). Update these documents with any process decisions made throughout the project
-[ ][Build a Product Backlog](agile-development/backlog-management/readme.md)
21
+
-[ ][Build a Product Backlog](agile-development/backlog-management/README.md)
22
22
- Set up a project in your chosen project management tool (ex. Azure DevOps)
23
23
-[INVEST](https://en.wikipedia.org/wiki/INVEST_(mnemonic)) in good User Stories and Acceptance Criteria
24
24
25
25
### Day 1
26
26
27
-
-[ ][Plan the first sprint](agile-development/sprint-planning/readme.md)
27
+
-[ ][Plan the first sprint](agile-development/sprint-planning/README.md)
28
28
- Agree on a sprint goal, and how to measure the sprint progress
29
29
- Determine team capacity
30
30
- Assign user stories to the sprint and split user stories into tasks
31
31
- Set up Work in Progress (WIP) limits
32
-
-[ ][Decide on test frameworks and discuss test strategies](automated-testing/readme.md)
32
+
-[ ][Decide on test frameworks and discuss test strategies](automated-testing/README.md)
33
33
- Discuss the purpose and goals of tests and how to measure test coverage
34
34
- Agree on how to separate unit tests from integration, load and smoke tests
35
35
- Design the first test cases
36
-
-[ ][Decide on branch naming](source-control/contributing/naming-branches.md)
36
+
-[ ][Decide on branch naming](source-control/naming-branches.md)
37
37
-[ ][Discuss security needs and verify that secrets are kept out of source control](continuous-delivery/secrets-management/recipes/azure-devops/secrets-per-branch.md)
38
38
39
39
### Day 2
40
40
41
-
-[ ][Set up Source Control](source-control/readme.md)
42
-
- Agree on [best practices for commits](source-control/readme.md#commit-best-practices)
43
-
-[ ][Set up basic Continuous Integration with linters and automated tests](continuous-integration/readme.md)
44
-
-[ ][Set up meetings for Daily Stand-ups and decide on a Process Lead](agile-development/stand-ups/readme.md)
41
+
-[ ][Set up Source Control](source-control/README.md)
42
+
- Agree on [best practices for commits](source-control/README.md#commit-best-practices)
43
+
-[ ][Set up basic Continuous Integration with linters and automated tests](continuous-integration/README.md)
44
+
-[ ][Set up meetings for Daily Stand-ups and decide on a Process Lead](agile-development/stand-ups/README.md)
45
45
- Discuss purpose, goals, participants and facilitation guidance
46
46
- Discuss timing, and how to run an efficient stand-up
47
-
-[ ][If the project has sub-teams, set up a Scrum of Scrums](agile-development/scrum-of-scrums/readme.md)
47
+
-[ ][If the project has sub-teams, set up a Scrum of Scrums](agile-development/scrum-of-scrums.md)
48
48
49
49
### Day 3
50
50
51
51
-[ ][Agree on code style](code-reviews/README.md) and on [how to assign Pull Requests](code-reviews/pull-requests.md)
52
-
-[ ][Set up Build Validation for Pull Requests (2 reviewers, linters, automated tests)](code-reviews/README.md) and agree on [Definition of Done](agile-development/team-agreements/definition-of-done/readme.md)
53
-
-[ ][Agree on a Code Merging strategy](source-control/contributing/merge-strategies.md) and update the [CONTRIBUTING.md](resources/templates/CONTRIBUTING.md)
54
-
-[ ][Agree on logging and observability frameworks and strategies](observability/readme.md)
52
+
-[ ][Set up Build Validation for Pull Requests (2 reviewers, linters, automated tests)](code-reviews/README.md) and agree on [Definition of Done](agile-development/team-agreements/definition-of-done.md)
53
+
-[ ][Agree on a Code Merging strategy](source-control/merge-strategies.md) and update the [CONTRIBUTING.md](resources/templates/CONTRIBUTING.md)
54
+
-[ ][Agree on logging and observability frameworks and strategies](observability/README.md)
55
55
56
56
### Day 4
57
57
58
-
-[ ][Set up Continuous Deployment](continuous-delivery/readme.md)
58
+
-[ ][Set up Continuous Deployment](continuous-delivery/README.md)
59
59
- Determine what environments are appropriate for this solution
60
60
- For each environment discuss purpose, when deployment should trigger, pre-deployment approvers, sing-off for promotion.
61
-
-[ ][Decide on a versioning strategy](source-control/versioning/readme.md)
62
-
-[ ] Agree on how to [Design a feature and conduct a Design Review](design-reviews/readme.md)
61
+
-[ ][Decide on a versioning strategy](source-control/component-versioning.md)
62
+
-[ ] Agree on how to [Design a feature and conduct a Design Review](design-reviews/README.md)
63
63
64
64
### Day 5
65
65
66
66
-[ ] Conduct a Sprint Demo
67
-
-[ ][Conduct a Retrospective](agile-development/retrospectives/readme.md)
67
+
-[ ][Conduct a Retrospective](agile-development/retrospectives.md)
68
68
- Determine required participants, how to capture input (tools) and outcome
69
69
- Set a timeline, and discuss facilitation, meeting structure etc.
70
-
-[ ][Refine the Backlog](agile-development/backlog-management/refinement/readme.md)
70
+
-[ ][Refine the Backlog](agile-development/backlog-management/backlog-refinement.md)
71
71
- Determine required participants
72
-
- Update the [Definition of Ready](agile-development/team-agreements/definition-of-ready/readme.md)
73
-
- Update estimates, and the [Estimation](agile-development/sprint-planning/estimation/readme.md) document
74
-
-[ ][Submit Engineering Feedback for issues encountered](engineering-feedback/readme.md)
72
+
- Update the [Definition of Ready](agile-development/team-agreements/definition-of-ready.md)
73
+
- Update estimates, and the [Estimation](agile-development/sprint-planning/estimation.md) document
74
+
-[ ][Submit Engineering Feedback for issues encountered](engineering-feedback/README.md)
0 commit comments