-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Organize and expand contributing documentation (#253)
* docs: Use title case consistently The sibling headings use title case. * docs: Relocate contributing guidelines into separate files Reduce the size of the `README` file and begin reorganizing code contribution guidelines to simplify navigating additional content. * docs: Expand the contributing guidelines * docs: Expand and improve consistency of code contribution documentation * docs: Document CLI development tips * docs: Fix documentation link paths * docs: Fix code of conduct link path * docs: Fix missing punctuation * docs: Add links to code contribution and project setup documentation * fix: Improve casing consistency * docs: Improve documentation formatting * docs: Simplify copying and pasting example commands * docs: Describe the Calypso project Contributors may not be familiar with the Calypso project or its purpose. Co-authored-by: Carlos Garcia <[email protected]> * docs: Further clarify Calypso's connection to WordPress.com Calypso is not associated with the open-source WordPress project. * docs: Recommend running `npm install` before building the source code Avoid potential confusion from missing or outdated dependencies by recommending that contributors always install the latest dependencies before building the source code. --------- Co-authored-by: Carlos Garcia <[email protected]>
- Loading branch information
Showing
3 changed files
with
171 additions
and
99 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # Contributing Guidelines | ||
|
|
||
| We welcome contributions to Studio, whether they are bug reports, feature requests, or code changes. Please read the following guidelines to ensure that your contributions are accepted quickly and easily. | ||
|
|
||
| ## Expectations | ||
|
|
||
| - We expect all contributors to follow our [Code of Conduct](./CODE-OF-CONDUCT.md). | ||
| - We expect all contributors to follow our [Security Policy](./SECURITY.md). | ||
| - By submitting a pull request, you agree to release your code under the project's [License](./LICENSE.md). | ||
|
|
||
| ## How to Contribute | ||
|
|
||
| ### Reporting Security Issues | ||
|
|
||
| Please see our [security policy](./SECURITY.md). | ||
|
|
||
| ### Reporting General Issues | ||
|
|
||
| If you find a bug or have a feature request, please [open an issue](https://github.com/Automattic/studio/issues/new/choose). | ||
|
|
||
| ### Code Contributions | ||
|
|
||
| For information on setting up your development environment for contributing code, see the [Code Contributions](./docs/code-contributions.md). | ||
|
|
||
| We are truly grateful for any pull requests you open, and we assure you of our welcoming and respectful approach. We will review and consider all pull requests, valuing the diverse contributions, but we don’t guarantee that all proposed changes will be merged into the core. | ||
|
|
||
| The most desirable pull requests are: | ||
|
|
||
| - Bug fixes for existing features. | ||
| - Enhancements that improve compatibility with different system versions, browsers, PHP or WP versions, WordPress plugins, or environments in general. | ||
|
|
||
| We recommend [adding an issue](https://github.com/Automattic/studio/issues/new/choose) for new features so we can review the plan before you start work on the pull request. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,135 @@ | ||
| # Code Contributions | ||
|
|
||
| ## Development | ||
|
|
||
| ### Required Dependencies | ||
|
|
||
| Before you can build and run the app, you need to install the following dependencies: | ||
|
|
||
| - [Node.js](https://nodejs.org/) - required JavaScript runtime environment. | ||
| - [Python](https://www.python.org/) - required for building native dependencies. | ||
| - [setuptools](https://pypi.org/project/setuptools/) - required for building native dependencies. | ||
|
|
||
| Many project contributors rely upon [`nvm`](https://github.com/nvm-sh/nvm) and [Homebrew](https://brew.sh) to manage Node.js and Python installations respectively. | ||
|
|
||
| If you manage packages with Homebrew you can do the following: | ||
|
|
||
| ```bash | ||
| brew install python3 python-setuptools | ||
| ``` | ||
|
|
||
| `nvm` commands referenced in the remaining documentation operate under the assumption that installed Node.js versions are managed with `nvm`. To use the correct Node.js version and install the project dependencies, run the following commands: | ||
|
|
||
| ```bash | ||
| nvm use | ||
| npm install | ||
| ``` | ||
|
|
||
| ### Running the App | ||
|
|
||
| Once all required dependencies are installed, you can run the app with the following command: | ||
|
|
||
| ```bash | ||
| npm install | ||
| npm start | ||
| ``` | ||
|
|
||
| The app automatically launches with the Chromium developer tools opened by default. Changes to the "renderer" process code will automatically reload the app, changes to the main process code require a manual server restart or [typing `rs`](https://www.electronforge.io/cli#start) into the same terminal where the server was started. | ||
|
|
||
| ### Project Structure | ||
|
|
||
| The following represents notable pieces of project structure: | ||
|
|
||
| - `scripts/` - scripts for building and testing the app. | ||
| - `src/` - the source code for the app. | ||
| - `src/index.ts` - the entry point for the main process. | ||
| - `src/renderer.ts` - the entry point for the "renderer," the code running in the Chromium window. | ||
| - `vendor/wp-now` - the modified `wp-now` source code. | ||
|
|
||
| ### Code Formatting | ||
|
|
||
| Code formatting is set up to make merging pull requests easier. It uses the same Prettier/ESLint mechanism as Calypso, the code powering the WordPress.com dashboard. See [JavaScript Coding Guidelines](https://github.com/Automattic/wp-calypso/blob/trunk/docs/coding-guidelines/javascript.md) for guidance on setting up your editor for code formatting. | ||
|
|
||
| ### CLI Development | ||
|
|
||
| The CLI relies upon a separate instance of the app to run. When developing the CLI, the CLI can be invoked with the following steps: | ||
|
|
||
| - Run `npm start` to launch the first instance of the app. | ||
| - Within the `forge.config.ts` file, change the `WebpackPlugin` ports used for the second instance: | ||
| - Set the development `port` to `3457`. | ||
| - Add a `loggerPort` property set to `9001`. | ||
| - Run `npm start -- -- --cli"=<CLI-COMMAND>"` in separate terminal session. | ||
|
|
||
| ## Testing | ||
|
|
||
| ### Unit Tests | ||
|
|
||
| Automated unit tests can be run with the following command: | ||
|
|
||
| ```bash | ||
| npm run test | ||
| ``` | ||
|
|
||
| Or to run tests in "watch" mode: | ||
|
|
||
| ```bash | ||
| npm run test:watch | ||
| ``` | ||
|
|
||
| ### End-to-End Tests | ||
|
|
||
| Automated end-to-end (E2E) tests are also available. To run them, clean the `out/` directory and build the fresh app binary: | ||
|
|
||
| ```bash | ||
| npm run make | ||
| ``` | ||
|
|
||
| Then run tests: | ||
|
|
||
| ```bash | ||
| npm run e2e | ||
| ``` | ||
|
|
||
| ## Debugging | ||
|
|
||
| The renderer process can be debugged using the Chromium developer tools. To open the developer tools, press <kbd>Cmd</kbd>+<kbd>Option</kbd>+<kbd>I</kbd> on Mac or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> on Windows. | ||
|
|
||
| The React tree in the renderer process can be debugged with the standalone [React Developer Tools](https://react.dev/learn/react-developer-tools#safari-and-other-browsers). To do this, start the the React Developer Tools and then start the app with the `REACT_DEV_TOOLS=true` flag set. | ||
|
|
||
| First, install and run the React Developer Tools: | ||
|
|
||
| ```bash | ||
| npx react-devtools | ||
| ``` | ||
|
|
||
| Then start the app with the `REACT_DEV_TOOLS=true` flag: | ||
|
|
||
| ```bash | ||
| REACT_DEV_TOOLS=true npm start | ||
| ``` | ||
|
|
||
| The main process can be debugged using the Node.js inspector. To do this, run the app with the `--inspect-brk-electron` flag: | ||
|
|
||
| ```bash | ||
| npm start -- --inspect-brk-electron | ||
| ``` | ||
|
|
||
| Then open `chrome://inspect` in a Chromium-based browser and click "inspect" next to the process you want to debug. | ||
|
|
||
| ## Building Installers | ||
|
|
||
| Once all required dependencies are installed, you can build installers for the app. | ||
| Installers can currently be built on Mac (Intel or Apple Silicon) and Windows with the following command: | ||
|
|
||
| ```bash | ||
| npm install | ||
| npm run make | ||
| ``` | ||
|
|
||
| ## Localization | ||
|
|
||
| See [Localization](./localization.md) documentation. | ||
|
|
||
| ## Versioning and Updates | ||
|
|
||
| See [Versioning and Updates](./versioning-and-updates.md) documentation. |