From 59dd2c1a123049e980555eb2ab11d65814f8d952 Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Thu, 29 Feb 2024 10:23:15 -0800 Subject: [PATCH 1/9] dev work flow updates --- docs/react-v9/contributing/dev-workflow.md | 94 +++++++++++++++++++++- 1 file changed, 91 insertions(+), 3 deletions(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 3c5aac9be546c..495d4f635d341 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -1,4 +1,92 @@ -// TODO #30642 A doc explaining day to day dev work flow. +## Making changes -Assignee - Mason -Reviewer - Sarah +### Creating a branch + +Create a branch from your fork for your code changes: + +``` +git checkout -b my-branch-name +``` + +We strongly recommend using the CLI as your primary interface with git. GUIs are useful for viewing diffs, creating branches and making quick commits. However they often do not correctly merge and sync working branches with master. Mistakes in this step are time consuming to fix. + +That said, some team members use [SourceTree](https://www.sourcetreeapp.com/), [GitHub app](https://desktop.github.com/) or the git integrations available in VS Code. + +We don't have an official branch naming policy. However some developers use the following to make their branches easier to find: user/[alias]/you-fancy-branch-name, ie user/johndoe/fix-that-bug + +### Building + +The inner development loop usually involves these steps: + +First, `cd` to the root folder of the repo (usually `fluentui`) and run `yarn` to install dependencies and link packages. + +``` +cd fluentui +yarn // this can take some time +``` + +Run `yarn start` and select your start up project. + +- @fluentui/public-docsite starts the public v8 documentation site. +- @fluentui/public-docsite-v9 starts the internal v9 documentation storybook site. +- Pick a specific component package if you intend to work on a v9 component directly. + +### Iterating + +Make the changes you need, and commit along the way. + +``` +git status // Shows all changed files +git add . // Stages the changed files +git commit -m "Your brief message." // Makes the commits. You may notice a slight lag during committing as our linters work away. +git push upstream // Pushes your changes to the central Fluent UI repo. +``` + +### Syncing with master + +It is strongly recommended that you rebase your branch onto (rather than merging with) with master. + +``` +git checkout master // Switches to master +git pull upstream master // Syncs your local master with the latest version of master at the origin +git checkout your-fancy-branch // Switches to your branch +git rebase master // Tacks your commits onto the end of master. +``` + +Resolve any conflicts in your editor. + +`git push upstream` // Pushes your changes to the central Fluent UI repo. + +Creating _draft_ pull requests is often an easy way to keep track of your work without it being actively reviewed by others. + +In other cases, such as before checking in or running tests, you may need to run a full build (or build up to a certain package): + +- `yarn build` - build everything. It is good the run this weekly, or anytime you start a new project off master. +- `yarn build --to package-name` - build up to a package. + - `yarn build --to @fluentui/react` + +You can also `cd` to any package under `packages/*` and run `yarn build` to build individual things, though keep in mind that this may require dependencies to be built first (using `build --to`). + +### Making a pull request + +Before creating a pull request, be sure to run `yarn change` and provide a high-level description of your change, which will be used in the release notes. When selecting a change type, use this guide: + +- Major - Don't do these without expressed agreement from the team. This is a very stable repo. +- Minor - Adding new API surface area. +- Patch - No change in API surface area. + +Make sure all your changes are committed, and run `yarn build`. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. + +When your change is ready, [create a pull request](https://github.com/microsoft/fluentui/pulls) from your branch to the `master` branch in `microsoft/fluentui`. + +Common checklist for PR's + +- Descriptive title: "Adding 'multiple' prop to Nav" +- Brief description of the improvement you're making. You may briefly summarize the issue. Assume the PR is the reviewers starting point and they should only have to dive into the issue for very specific details. +- Link to the relevant issue. +- Visual aid for changes to give more context. Before and After clips help a lot. +- Open questions - Point reviewers to places in your code you're looking for specific feedback on. +- How to test - Briefly explain how a reviewer can test your code. +- Reviewers will be automatically added based on the location of the changes in the code base. + +Once signed off, it's up to the author to hit the big green button! 🎉 From c0a08e50e5be13a6d2e67d708c7f1fa8e0e57b0f Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Thu, 29 Feb 2024 10:28:07 -0800 Subject: [PATCH 2/9] more tweaks --- docs/react-v9/contributing/dev-workflow.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 495d4f635d341..4e7fce8c15898 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -31,6 +31,8 @@ Run `yarn start` and select your start up project. - @fluentui/public-docsite-v9 starts the internal v9 documentation storybook site. - Pick a specific component package if you intend to work on a v9 component directly. +Most projects have hot module reloading, so file saves will trigger refreshes. + ### Iterating Make the changes you need, and commit along the way. From c4b36664354a1a60faef308847c0380d6445725b Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Fri, 1 Mar 2024 10:32:10 -0800 Subject: [PATCH 3/9] Update dev-workflow.md --- docs/react-v9/contributing/dev-workflow.md | 30 +++++++++++++--------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 4e7fce8c15898..68c033bd2d8c9 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -2,7 +2,7 @@ ### Creating a branch -Create a branch from your fork for your code changes: +Create a branch from your forked branch for your code changes: ``` git checkout -b my-branch-name @@ -12,7 +12,7 @@ We strongly recommend using the CLI as your primary interface with git. GUIs are That said, some team members use [SourceTree](https://www.sourcetreeapp.com/), [GitHub app](https://desktop.github.com/) or the git integrations available in VS Code. -We don't have an official branch naming policy. However some developers use the following to make their branches easier to find: user/[alias]/you-fancy-branch-name, ie user/johndoe/fix-that-bug +We don't have an official branch naming policy. However some developers use the following to make their branches easier to find: `user/[alias]/your-fancy-branch-name`, ie `user/johndoe/fix-that-bug`. ### Building @@ -27,9 +27,12 @@ yarn // this can take some time Run `yarn start` and select your start up project. -- @fluentui/public-docsite starts the public v8 documentation site. -- @fluentui/public-docsite-v9 starts the internal v9 documentation storybook site. -- Pick a specific component package if you intend to work on a v9 component directly. +``` +@fluentui/public-docsite // starts the public v8 documentation site. +@fluentui/public-docsite-v9 // starts the internal v9 documentation storybook site. +``` + +Pick a specific component package if you intend to work on a v9 component directly. Most projects have hot module reloading, so file saves will trigger refreshes. @@ -46,7 +49,7 @@ git push upstream // Pushes your changes to the central Fluent UI repo. ### Syncing with master -It is strongly recommended that you rebase your branch onto (rather than merging with) with master. +It is strongly recommended that you rebase your branch onto (rather than merging with) master. ``` git checkout master // Switches to master @@ -64,31 +67,34 @@ Creating _draft_ pull requests is often an easy way to keep track of your work w In other cases, such as before checking in or running tests, you may need to run a full build (or build up to a certain package): - `yarn build` - build everything. It is good the run this weekly, or anytime you start a new project off master. -- `yarn build --to package-name` - build up to a package. - - `yarn build --to @fluentui/react` +- `yarn buildto package-name` - build up to a package. + - `yarn buildto @fluentui/react` You can also `cd` to any package under `packages/*` and run `yarn build` to build individual things, though keep in mind that this may require dependencies to be built first (using `build --to`). ### Making a pull request +Make sure all your changes are committed, and run a build on the package that was updated, e.g. `yarn workspace @fluentui/react-components build` for changes to the v9 components. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. + Before creating a pull request, be sure to run `yarn change` and provide a high-level description of your change, which will be used in the release notes. When selecting a change type, use this guide: - Major - Don't do these without expressed agreement from the team. This is a very stable repo. - Minor - Adding new API surface area. - Patch - No change in API surface area. -Make sure all your changes are committed, and run `yarn build`. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. +After choosing a change type, the description should follow the [semantic commit message format](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716), and be prepended by one of the following: `feat:`, `fix:`, `chore:`, `docs:`, or `refactor:`. When your change is ready, [create a pull request](https://github.com/microsoft/fluentui/pulls) from your branch to the `master` branch in `microsoft/fluentui`. Common checklist for PR's -- Descriptive title: "Adding 'multiple' prop to Nav" -- Brief description of the improvement you're making. You may briefly summarize the issue. Assume the PR is the reviewers starting point and they should only have to dive into the issue for very specific details. +- Descriptive title: "feat: Adding 'multiple' prop to Nav" +- Brief description of the improvement you're making. You may briefly summarize the issue. Assume the PR is the reviewer's starting point and they should only have to dive into the issue for very specific details. - Link to the relevant issue. - Visual aid for changes to give more context. Before and After clips help a lot. - Open questions - Point reviewers to places in your code you're looking for specific feedback on. - How to test - Briefly explain how a reviewer can test your code. - Reviewers will be automatically added based on the location of the changes in the code base. -Once signed off, it's up to the author to hit the big green button! 🎉 +If you're using an internal Microsoft linked account, feel free to squash that big green button. 🎉 +If you're not using a Microsoft linked account, someone from the team will have to merge it for you. Thanks for the contribution! 🙏 From 9728e7630136c1256b12e7464a7bd5da42ad863c Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Fri, 1 Mar 2024 10:55:44 -0800 Subject: [PATCH 4/9] more updates --- docs/react-v9/contributing/dev-workflow.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 68c033bd2d8c9..99d306b94e3ed 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -4,9 +4,9 @@ Create a branch from your forked branch for your code changes: -``` +\``` git checkout -b my-branch-name -``` +\``` We strongly recommend using the CLI as your primary interface with git. GUIs are useful for viewing diffs, creating branches and making quick commits. However they often do not correctly merge and sync working branches with master. Mistakes in this step are time consuming to fix. @@ -18,11 +18,11 @@ We don't have an official branch naming policy. However some developers use the The inner development loop usually involves these steps: -First, `cd` to the root folder of the repo (usually `fluentui`) and run `yarn` to install dependencies and link packages. +First, `cd` to the root folder of the repo (usually `fluentui`) and run `yarn` to install dependencies and link packages. This can take some time. ``` cd fluentui -yarn // this can take some time +yarn ``` Run `yarn start` and select your start up project. @@ -76,10 +76,10 @@ You can also `cd` to any package under `packages/*` and run `yarn build` to buil Make sure all your changes are committed, and run a build on the package that was updated, e.g. `yarn workspace @fluentui/react-components build` for changes to the v9 components. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. -Before creating a pull request, be sure to run `yarn change` and provide a high-level description of your change, which will be used in the release notes. When selecting a change type, use this guide: +Before creating a pull request, be sure to run `yarn change` and provide a high-level description of your change, which will be used in the release notes. We follow [semantic versioning](https://semver.org/), so use the guide when selecting a change type: -- Major - Don't do these without expressed agreement from the team. This is a very stable repo. -- Minor - Adding new API surface area. +- Major - Don't do these without expressed agreement from the team. This is a very stable repo. This option is usually disabled. +- Minor - Adding new API surface area that is backwards compatible and does not dramatically change the intent of an API. - Patch - No change in API surface area. After choosing a change type, the description should follow the [semantic commit message format](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716), and be prepended by one of the following: `feat:`, `fix:`, `chore:`, `docs:`, or `refactor:`. From 599400a68c964a399875256010439d488cb030eb Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Tue, 5 Mar 2024 14:45:10 -0800 Subject: [PATCH 5/9] updates --- docs/react-v9/contributing/dev-workflow.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 99d306b94e3ed..7446231577e5d 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -2,9 +2,11 @@ ### Creating a branch -Create a branch from your forked branch for your code changes: +Create a branch from your forked repo for your code changes: \``` +git checkout master +git pull upstream master git checkout -b my-branch-name \``` @@ -76,6 +78,8 @@ You can also `cd` to any package under `packages/*` and run `yarn build` to buil Make sure all your changes are committed, and run a build on the package that was updated, e.g. `yarn workspace @fluentui/react-components build` for changes to the v9 components. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. +If your changes make any changes or additions to the DOM, you may need to run `yarn update-snapshots`. Check these updates in. + Before creating a pull request, be sure to run `yarn change` and provide a high-level description of your change, which will be used in the release notes. We follow [semantic versioning](https://semver.org/), so use the guide when selecting a change type: - Major - Don't do these without expressed agreement from the team. This is a very stable repo. This option is usually disabled. From 429f9b12f13fa386a56154473ad8fd3ab6c58bd5 Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Mon, 11 Mar 2024 08:57:18 -0700 Subject: [PATCH 6/9] more updates --- docs/react-v9/contributing/dev-workflow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 7446231577e5d..86b834ec33192 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -46,7 +46,7 @@ Make the changes you need, and commit along the way. git status // Shows all changed files git add . // Stages the changed files git commit -m "Your brief message." // Makes the commits. You may notice a slight lag during committing as our linters work away. -git push upstream // Pushes your changes to the central Fluent UI repo. +git push // Pushes your changes to your forked branch. ``` ### Syncing with master @@ -62,7 +62,7 @@ git rebase master // Tacks your commits onto the end of master. Resolve any conflicts in your editor. -`git push upstream` // Pushes your changes to the central Fluent UI repo. +`git push` // Pushes your changes to your forked branch. Creating _draft_ pull requests is often an easy way to keep track of your work without it being actively reviewed by others. From 1dfa8c36c583db2bb69758e7479561472ec75d7e Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Mon, 1 Apr 2024 09:51:06 -0700 Subject: [PATCH 7/9] Martin's feedback --- docs/react-v9/contributing/dev-workflow.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 86b834ec33192..78beb253ebfb5 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -46,7 +46,7 @@ Make the changes you need, and commit along the way. git status // Shows all changed files git add . // Stages the changed files git commit -m "Your brief message." // Makes the commits. You may notice a slight lag during committing as our linters work away. -git push // Pushes your changes to your forked branch. +git push --force// Pushes your changes to your forked branch. ``` ### Syncing with master @@ -57,7 +57,7 @@ It is strongly recommended that you rebase your branch onto (rather than merging git checkout master // Switches to master git pull upstream master // Syncs your local master with the latest version of master at the origin git checkout your-fancy-branch // Switches to your branch -git rebase master // Tacks your commits onto the end of master. +git rebase -i master // Tacks your commits onto the end of master. Force is necessary since rebase changes history. ``` Resolve any conflicts in your editor. @@ -68,17 +68,15 @@ Creating _draft_ pull requests is often an easy way to keep track of your work w In other cases, such as before checking in or running tests, you may need to run a full build (or build up to a certain package): -- `yarn build` - build everything. It is good the run this weekly, or anytime you start a new project off master. +- `yarn lage build --since master` - build everything. It is good the run this weekly, or anytime you start a new project off master. - `yarn buildto package-name` - build up to a package. - `yarn buildto @fluentui/react` -You can also `cd` to any package under `packages/*` and run `yarn build` to build individual things, though keep in mind that this may require dependencies to be built first (using `build --to`). - ### Making a pull request -Make sure all your changes are committed, and run a build on the package that was updated, e.g. `yarn workspace @fluentui/react-components build` for changes to the v9 components. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. +Make sure all your changes are committed, and run `yarn nx run @fluentui/react-components:build` or `yarn buildto @fluentui/react-components` for changes to the v9 components. This will compare your changes and detect if the publicly facing API has changed, and update the right docs accordingly. Commit this change. -If your changes make any changes or additions to the DOM, you may need to run `yarn update-snapshots`. Check these updates in. +If your changes make any changes or additions to the DOM, you may need to run `yarn nx run @fluentui/:test -u` or `yarn workspace @fluentui/ test --updateSnapshot`. Check these updates in. Before creating a pull request, be sure to run `yarn change` and provide a high-level description of your change, which will be used in the release notes. We follow [semantic versioning](https://semver.org/), so use the guide when selecting a change type: @@ -86,18 +84,18 @@ Before creating a pull request, be sure to run `yarn change` and provide a high- - Minor - Adding new API surface area that is backwards compatible and does not dramatically change the intent of an API. - Patch - No change in API surface area. -After choosing a change type, the description should follow the [semantic commit message format](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716), and be prepended by one of the following: `feat:`, `fix:`, `chore:`, `docs:`, or `refactor:`. +After choosing a change type, the description should follow the [semantic commit message format](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716), and be prepended by one of the following: `feat:`, `fix:`, `chore:`, `docs:`, or `refactor:`. Use [this guide](https://www.conventionalcommits.org/en/v1.0.0/#summary) for more guidance on how to write your change log files. When your change is ready, [create a pull request](https://github.com/microsoft/fluentui/pulls) from your branch to the `master` branch in `microsoft/fluentui`. Common checklist for PR's - Descriptive title: "feat: Adding 'multiple' prop to Nav" -- Brief description of the improvement you're making. You may briefly summarize the issue. Assume the PR is the reviewer's starting point and they should only have to dive into the issue for very specific details. +- Brief description of the improvement you're making. You should summarize the issue you are addressing. Assume the PR is the reviewer's starting point and they should only have to dive into the issue for very specific details. - Link to the relevant issue. - Visual aid for changes to give more context. Before and After clips help a lot. - Open questions - Point reviewers to places in your code you're looking for specific feedback on. -- How to test - Briefly explain how a reviewer can test your code. +- How to test - Briefly explain how a reviewer can test your code, and what they should focus on. - Reviewers will be automatically added based on the location of the changes in the code base. If you're using an internal Microsoft linked account, feel free to squash that big green button. 🎉 From cbd24f9ff0adaf58771c306209295b10f93fc5ea Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Mon, 1 Apr 2024 09:56:46 -0700 Subject: [PATCH 8/9] use more force --- docs/react-v9/contributing/dev-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index 78beb253ebfb5..fb8f3f5f13327 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -62,7 +62,7 @@ git rebase -i master // Tacks your commits onto the end of master. Force is nece Resolve any conflicts in your editor. -`git push` // Pushes your changes to your forked branch. +`git push upstream --force` // Pushes your changes to your forked branch. Include `upstream` if you have an open pull request, otherwise do not include it. Creating _draft_ pull requests is often an easy way to keep track of your work without it being actively reviewed by others. From b1879eb7f0e4a4a2b27793e97777112db9d732ca Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Thu, 4 Apr 2024 11:30:11 -0700 Subject: [PATCH 9/9] final updates from martin --- docs/react-v9/contributing/dev-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/react-v9/contributing/dev-workflow.md b/docs/react-v9/contributing/dev-workflow.md index fb8f3f5f13327..cb6b5f955d7b7 100644 --- a/docs/react-v9/contributing/dev-workflow.md +++ b/docs/react-v9/contributing/dev-workflow.md @@ -14,7 +14,7 @@ We strongly recommend using the CLI as your primary interface with git. GUIs are That said, some team members use [SourceTree](https://www.sourcetreeapp.com/), [GitHub app](https://desktop.github.com/) or the git integrations available in VS Code. -We don't have an official branch naming policy. However some developers use the following to make their branches easier to find: `user/[alias]/your-fancy-branch-name`, ie `user/johndoe/fix-that-bug`. +We don't have an official branch naming policy. Since every contribution happens from your personal fork, there's little risk of naming clashes. However some developers use the following to make their branches easier to find: `user/[alias]/your-fancy-branch-name`, ie `user/jdoe/fix-that-bug`. ### Building @@ -68,8 +68,8 @@ Creating _draft_ pull requests is often an easy way to keep track of your work w In other cases, such as before checking in or running tests, you may need to run a full build (or build up to a certain package): -- `yarn lage build --since master` - build everything. It is good the run this weekly, or anytime you start a new project off master. -- `yarn buildto package-name` - build up to a package. +- `yarn lage build --since master` - build everything. You shouldn't need to do this for regular work flow. +- `yarn buildto package-name` - build up to a package. It is good to run this weekly, or anytim you start a new project off master. - `yarn buildto @fluentui/react` ### Making a pull request