From ec83e994ef3b29a2ae779d79b928011e7d78cd01 Mon Sep 17 00:00:00 2001 From: Paul Stelzer Date: Tue, 18 Dec 2018 15:54:36 +0100 Subject: [PATCH] docs(contributing): update steps for v4 (#16705) resolves #16672 --- .github/CONTRIBUTING.md | 102 +++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 44 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e5937a2e05..a241f95dc6 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -16,11 +16,11 @@ Please see our [Contributor Code of Conduct](https://github.com/ionic-team/ionic * The issue list of this repository is exclusively for bug reports and feature requests. Non-conforming issues will be closed immediately. -* Issues with no clear steps to reproduce will not be triaged. If an issue is labeled with "needs reply" and receives no further replies from the author of the issue for more than 5 days, it will be closed. +* Issues with no clear steps to reproduce will not be triaged. If an issue is labeled with "needs: reply" and receives no further replies from the author of the issue for more than 30 days, it will be closed. * If you think you have found a bug, or have a new feature idea, please start by making sure it hasn't already been [reported](https://github.com/ionic-team/ionic/issues?utf8=%E2%9C%93&q=is%3Aissue). You can search through existing issues to see if there is a similar one reported. Include closed issues as it may have been closed with a solution. -* Next, [create a new issue](https://github.com/ionic-team/ionic/issues/new) that thoroughly explains the problem. Please fill out the populated issue form before submitting the issue. +* Next, [create a new issue](https://github.com/ionic-team/ionic/issues/new/choose) that thoroughly explains the problem. Please fill out the populated issue form before submitting the issue. ## Creating a Pull Request @@ -29,66 +29,80 @@ Please see our [Contributor Code of Conduct](https://github.com/ionic-team/ionic * Looking for an issue to fix? Make sure to look through our issues with the [help wanted](https://github.com/ionic-team/ionic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) label! + ### Setup -1. Fork the repo. -2. Clone your fork. -3. Make a branch for your change. -4. Run `npm install` (make sure you have [node](https://nodejs.org/en/) and [npm](http://blog.npmjs.org/post/85484771375/how-to-install-npm) installed first) +1. [Download the installer](https://nodejs.org/) for the LTS version of Node.js. This is the best way to also [install npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_). +2. Fork this repository. +3. Clone your fork. +4. Create a new branch from master for your change. +5. Navigate into the directory of the package you wish to modify (core, angular, etc.). +6. Run `npm install` to install dependencies for this package. +7. Follow the steps for the specific package below. -### Modifying Components +### Core -1. Make any changes to the component. -2. Modify the e2e test in the `test/` directory under the component directory, if possible. If the test does not exist and it is possible to show the change, please create a new test in a directory called `basic/`. +#### Modifying Components + +1. Locate the component(s) to modify inside `/core/src/components/`. +2. Take a look at the [Stencil Documentation](https://stenciljs.com/docs/introduction/) and other components to understand the implementation of these components. +3. Make your changes to the component. If the change is overly complex or out of the ordinary, add comments so we can understand the changes. +4. [Preview your changes](#preview-changes) locally. +5. [Modify the documentation](#modifying-documentation) if needed. +6. [Run lint](#lint-changes) on the directory and make sure there are no errors. +7. [Build the project](#building-changes). +8. After the build is finished, commit the changes. Please follow the [commit message format](#commit-message-format) for every commit. +9. [Submit a Pull Request](#submit-pull-request) of your changes. -#### TypeScript Changes +#### Preview Changes -1. If there is a `*.spec.ts` file located in the `test/` folder, update it to include a karma test for your change, if needed. If this file doesn't exist, please notify us. -2. Run `gulp test` to make sure all tests are working, regardless if a test was added. -3. Run `gulp lint.ts` and fix any linter errors. +1. Run `npm start` from within the `core` directory. +2. A browser should open at `http://localhost:3333/`. +3. From here, navigate to one of the component's tests to preview your changes. +4. If a test showing your change doesn't exist, [add a new test or update an existing one](#modifying-tests). -#### Sass Changes +#### Lint Changes -1. After any changes to the Sass files run [stylelint](https://stylelint.io/): - - Switch to the `core` directory - - Run `npm run lint.sass` and manually fix the errors or `npm run lint.fix` to autofix the errors - -#### Viewing Changes - -1. Run the gulp e2e task to build all tests: `gulp e2e` -2. Run the gulp e2e.watch task to watch your specific test (replace `button` with the component you are modifying and `basic` with the test folder): `gulp e2e.watch --f=button/basic` -3. A browser should open at `http://localhost:8080/dist/e2e`. From here, navigate to the component you are changing. -4. If your changes look good, you're ready to [commit](#commit-message-format)! +1. Run `npm run lint` to lint the TypeScript and Sass. +2. If there are lint errors, run `npm run lint.fix` to automatically fix any errors. Repeat step 1 to ensure the errors have been fixed, and manually fix them if not. +3. To lint and fix only TypeScript errors, run `npm run lint.ts` and `npm run lint.ts.fix`, respectively. +4. To lint and fix only Sass errors, run `npm run lint.sass` and `npm run lint.sass.fix`, respectively. -#### Adding Documentation +#### Modifying Documentation -1. To add or modify API Documentation for a component, it should be added/changed in the `readme.md` file in the component's directory. If the updates are to a specific `@Prop`, `@Event` or `@Method`, then please make the changes to the component's TypeScript (`*.ts`). Properties, events and methods information within the `readme.md` file are auto generated directly from the JSDoc comments within the TypeScript file. -2. In order to run API documentation locally, you will need to clone the `ionic-site` repo as a sibling to the `ionic` repo and then run it: https://github.com/ionic-team/ionic-site#local-build -3. Then, run `gulp docs` in the `ionic` repo every time you make a change and the site will update. -4. If the change affects the component documentation, create an issue on the `ionic-site` repo: https://github.com/ionic-team/ionic-site/issues +1. Locate the `readme.md` file in the component's directory. +2. Modify the documentation **above** the line that says `` in this file. +3. To update any of the auto generated documentation below that line, make the relevant changes in the following places: + - `Usage`: update the component's usage examples in the component's `usage/` directory + - `Properties`, `Events`, or `Methods`: update the component's TypeScript file (`*.tsx`) + - `CSS Custom Properties`: update the component's main Sass file (`*.scss`) -#### Adding Demos +#### Modifying Tests -1. Create or modify the demo in the `demos/` folder. -2. If it is new, link to the demo in the component's TypeScript (`*.ts`) file (under `src/components`) by adding a link to it in the documentation using `@demo`, for example: +1. Locate the test to modify inside the `test/` folder in the component's directory. +2. If a test exists, modify the test by adding an example to reproduce the problem fixed or feature added. +3. If a new test is needed, the easiest way is to copy the `basic/` directory from the component's `test/` directory, rename it, and edit the content in both the `index.html` and `e2e.ts` file (if it exists). +4. The `preview/` directory is used in the documentation as a demo. Only update this test if there is a bug in the test or if the API has a change that hasn't been updated in the test. - ``` - /** - * @name Badge - * - * ... - * - * @demo /docs/v2/demos/src/badge/ - **/ - ``` -3. Run `gulp watch.demos` to watch for changes to the demo -4. Navigate to `http://localhost:8000/dist/demos/` and then to your component's demo to view it. -5. If the change affects the component demos, create an issue on the `ionic-site` repo: https://github.com/ionic-team/ionic-site/issues + +#### Building Changes + +1. Once all changes have been made and the documentation has been updated, run `npm run build` inside of the `core` directory. This will add your changes to any auto-generated files, if necessary. +2. Review the changes and, if everything looks correct, [commit](#commit-message-format) the changes. +3. Make sure the build has finished before committing. If you made changes to the documentation, properties, methods, or anything else that requires an update to a generate file, this needs to be committed. +4. After the changes have been pushed, publish the branch and [create a pull request](#creating-a-pull-request). + + +### Submit Pull Request + +1. [Create a new pull request](https://github.com/ionic-team/ionic/compare) with the `master` branch as the `base`. You may need to click on `compare across forks` to find your changes. +2. See the [Creating a pull request from a fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) GitHub help article for more information. +3. Please fill out the provided Pull Request template to the best of your ability and include any issues that are related. ## Commit Message Format