Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (44 loc) · 5.95 KB

CONTRIBUTING.md

File metadata and controls

67 lines (44 loc) · 5.95 KB
Raw

Development setup

We welcome any quality bugfixes or contributions!

To avoid conflicts with your existing installation, it is recommended to delete the installed extension at:

  • Linux and macOS: ~/.vscode/extensions/msjsdiag.vscode-react-native-<version>
  • Windows: C:\Users\<username>\.vscode\extensions\msjsdiag.vscode-react-native-<version>

Build the project

  • git clone https://github.com/microsoft/vscode-react-native.git
  • cd vscode-react-native
  • Run npm ci
  • Run npm install -g gulp-cli and add "gulp.autoDetect": "on" to your VS Code settings
  • Run gulp and check dist folder for extension files (now the tasks from gulpfile.js are being exported following the latest guidance from https://gulpjs.com/docs/en/getting-started/creating-tasks/ as the task() API isn't the recommended pattern anymore)
  • After completing above steps, run gulp release to package extension .vsix file. A VSIX package can help you install the latest extension maunally in VS Code extension tab.

Debugging

There are currently 2 components to our extension: The extension running in the VS Code process with the debug adapter, and some code wrapping the user React Native code which is launched by the debug adapter. These are all debugged in different ways:

  • To debug the extension process itself and the debug adapter it provides, in VS Code run the Launch Extension debug target which will spawn a new instance of VS Code with the extension installed. You can set breakpoints in the Typescript and debug things such as extension activation and the command palette.

  • To debug the code running in the same process as the React Native code, open a React Native project, start debugging and find the debuggerWorker.js file where you can set a breakpoint. This file is generated by Metro bundler, but modified by the extension and saved in your React Native .vscode/.react folder locally. The file is created only when you start debugging against your React Native application and the debugger is already attached to it. The debuggerWorker.js is launched in --inspect-brk mode so it will wait until debugger is attached to the app.

  • To debug the gulpfile.js, add a configuration to .vscode/launch.json to run "${workspaceRoot}/node_modules/gulp/bin/gulp.js". Then we can run it through "Run and Debug" tab in VS Code.

Testing

The extension has Mocha-based extension tests, localization tests, and end-to-end smoke tests. The commands below serve different purposes:

  • npm test runs the extension tests in a VS Code Extension Host. Build the project first with npm run build (or npx gulp) so the test runner and extension JavaScript are up to date. In VS Code, use the Launch Extension tests configuration.
  • npm run test-localization runs the localization tests in a VS Code Extension Host. In VS Code, use the Launch Localization Tests configuration.
  • npx gulp test:coverage builds the development version and runs the extension tests with NYC coverage instrumentation. It writes text and HTML coverage reports under coverage/; no minimum coverage threshold is currently enforced.
  • npx gulp test-no-build invokes the extension test runner without building or linting first. Use it only when the generated JavaScript is already up to date.
  • npx gulp watch-build-test builds and tests once, then watches source and test files and repeats the build and tests after changes.
  • npm run smoke-tests runs the end-to-end smoke tests in test/smoke using a separate VS Code installation. It is not part of npm test.

To prepare smoke tests, run npm run prepare-smoke-tests from the repository root. If you are running scenarios that use the sample React Native project, also run npm run prepare-smoke-tests-project. The smoke test package and setup details are documented in test/smoke/README.md. In VS Code, Launch Smoke Tests compiles the smoke tests before running them; the required smoke-test dependencies must already be installed.

Run npx gulp lint to check formatting and lint rules, or npx gulp format to apply automatic formatting and lint fixes.

Legal

You must complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright.

Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign the agreement digitally. Alternatively, download the agreement from (Microsoft Contribution License Agreement.docx or Microsoft Contribution License Agreement.pdf), sign, scan, and email it back to cla@microsoft.com. Be sure to include your github user name along with a copy of the signed agreement. Once we have received the signed CLA, we'll review the request.

Sending a PR

Pull requests should:

  • Include a clear description of the proposed change
  • Be a child commit of a reasonably recent commit in the master branch
    • Requests need not be a single commit, but should be a linear sequence of commits (i.e. no merge commits in your PR)
  • Have clear commit messages
    • e.g. "Refactor feature", "Fix issue", "Add tests for issue"
  • Include adequate tests
    • At least one test should fail in the absence of your non-test code changes. If your PR does not match this criteria, please specify why
    • Tests should include reasonable permutations of the target fix/change
    • Include baseline changes with your change
  • Have linting issues (gulp lint)

It is desirable, but not necessary, for the tests to pass at each commit.

To avoid line ending issues, set autocrlf = input and whitespace = cr-at-eol in your system's git configuration.