diff --git a/_data/navigation.yaml b/_data/navigation.yaml index 344a012..b1219de 100644 --- a/_data/navigation.yaml +++ b/_data/navigation.yaml @@ -6,7 +6,7 @@ top_nav: url: /pages/tags/alpha - title: GitHub - url: /pages/resources/github + url: /pages/contributing/github - title: Help url: /pages/resources/help @@ -97,11 +97,19 @@ docs_nav: url: /pages/tags/virtual + - title: Contributing + subitems: + - title: GitHub + url: /pages/contributing/github + - title: Building the projects + url: /pages/contributing/building + - title: Submitting a PR + url: /pages/contributing/pr_checklist + + - title: Resources subitems: - title: Getting help url: /pages/resources/help - title: TSDoc Playground url: /play - - title: GitHub - url: /pages/resources/github diff --git a/pages/contributing/building.md b/pages/contributing/building.md new file mode 100644 index 0000000..bc73a7c --- /dev/null +++ b/pages/contributing/building.md @@ -0,0 +1,83 @@ +--- +layout: page +title: Building the projects +navigation_source: docs_nav +--- + +If you're going to submit a pull request for TSDoc, you will need to use the Rush monorepo manager tool. + +> **What's this Rush thing?** Rush is a monorepo build orchestrator that handles policy validation, +> change log management, installing (using [PNPM](https://pnpm.js.org/)), linking, building, +> and publishing. To learn more about Rush, please visit: [https://rushjs.io](https://rushjs.io) + +Install the tool like this: + +```shell +$ npm install -g @microsoft/rush +``` + +*NOTE: If this command fails because your user account does not have permissions to +access NPM's global folder, you may need to +[fix your NPM configuration](https://docs.npmjs.com/getting-started/fixing-npm-permissions).* + +Rush will symlink the **api-demo** project to use your local build of the **@microsoft/tsdoc** library, +for easy testing/validation. + +To build the projects: + +```shell +$ cd ./tsdoc +$ rush install +$ rush build +``` + + +## To run all the unit tests from the command-line + +The unit tests are implemented using [Jest](https://jestjs.io/), but invoked via the +[Heft](https://www.npmjs.com/package/@rushstack/heft) build system. +(See the linked pages for more comprehensive documentation.) + +The unit tests are invoked automatically when you build a project: + +```shell +$ cd ./tsdoc +$ npm run build +``` + + +## Running the unit tests interactively + +You can also invoke Heft/Jest interactively (the `jest --watch` scenario), so that affected tests will be +re-run whenever a source file is saved. Launch the watch mode like this: + +```shell +$ cd ./tsdoc +$ npm run watch +``` + + +## Debugging the unit tests + +The [./tsdoc/.vscode/launch.json](./tsdoc/.vscode/launch.json) file includes a +[Visual Studio Code](https://code.visualstudio.com/) configuration that makes debugging +easier. To debug a unit test: + +1. Launch VS Code in the tsdoc subfolder (not the repository root): + + ```shell + $ cd ./tsdoc + $ code . + ``` + +2. In the editor window, open a test file. For example, **src/__tests__/ParsingBasicTests.test.ts**. + +3. In the VS Code window, click **View --> Debug** (CTRL+SHIFT+D) + +4. From the DEBUG combo box, choose the "**Debug Jest tests**" debug configuration, and click the play button. +This will run all tests in the debugger. + +

+👉 Next: Submitting a pull request +

+ diff --git a/pages/resources/github.md b/pages/contributing/github.md similarity index 84% rename from pages/resources/github.md rename to pages/contributing/github.md index 6bc5e44..71bce72 100644 --- a/pages/resources/github.md +++ b/pages/contributing/github.md @@ -21,3 +21,8 @@ Supplementary project folders are: The `tsdoc.org` website is hosted in this Github repo: [https://github.com/microsoft/tsdoc.org-website](https://github.com/microsoft/tsdoc.org-website) + + +

+👉 Next: Building the projects +

diff --git a/pages/contributing/pr_checklist.md b/pages/contributing/pr_checklist.md new file mode 100644 index 0000000..fc59422 --- /dev/null +++ b/pages/contributing/pr_checklist.md @@ -0,0 +1,66 @@ +--- +layout: page +title: Submitting a pull request +navigation_source: docs_nav +--- + +1. Make sure the Rush tool is installed, following the +[Building the projects]({% link pages/contributing/building.md %}) instructions. + +2. Install dependencies for all projects in the monorepo: + + ```shell + # Run this command in the folder where you cloned the TSDoc repo from GitHub + $ rush install + ``` + + > Note: After you run `rush install`, your repo will be in a "Rush-linked" state, + > with special symlinks in the node_modules folders. DO NOT run `npm install` in this state. + > If you want to go back to working in standalone mode, first run `rush unlink && rush purge`. + +3. Build and test all the projects in the monorepo: + + ```shell + $ rush build + ``` + + You can also build just the **@microsoft/tsdoc** library like this: + + ```shell + $ cd ./tsdoc + $ npm run build + ``` + +4. Manual testing: Before submitting your PR, you should also try running the + [/api-demo](./api-demo/) and [/playground](./playground) projects to make sure they + weren't broken by your change. + +5. Change logs: If your PR modifies the published NPM package, you will need to write a + change entry for our [CHANGELOG.md](./tsdoc/CHANGELOG.md) change log. Please read the + "[recommended practices](https://rushjs.io/pages/best_practices/change_logs/)" for + authoring change logs. + + ```shell + $ rush change + # (The tool will ask you to write a sentence describing your change.) + ``` + + The `rush change` command will create a file under the **common/changes** folder. + Add this file to Git and include in your pull request. Please see + [Everyday commands](https://rushjs.io/pages/developer/everyday_commands/) for + more details about how these files are used. + + +## Contributor Notice + +This project welcomes contributions and suggestions. Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit https://cla.microsoft.com. + +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.