From 613cad47d006fc258b1356054ac8b575c89d20a0 Mon Sep 17 00:00:00 2001 From: Matt Netkow Date: Tue, 17 Mar 2020 17:16:33 -0500 Subject: [PATCH 1/3] update site contributing readme --- README.md | 2 ++ site/CONTRIBUTING.md | 80 +++++++------------------------------------- 2 files changed, 15 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index cee49cdad..cd1d5842f 100644 --- a/README.md +++ b/README.md @@ -33,5 +33,7 @@ Contributing to Capacitor may involve writing TypeScript, Swift/Objective-C, Jav Please read the [Contributing](.github/CONTRIBUTING.md) guide for more information. +For details on updating the Capacitor website or documentation, [see here](.github/site/CONTRIBUTING.md). + [circle-badge]: https://circleci.com/gh/ionic-team/capacitor.svg?style=shield [circle-badge-url]: https://circleci.com/gh/ionic-team/capacitor diff --git a/site/CONTRIBUTING.md b/site/CONTRIBUTING.md index 1731dd78c..8ceadea32 100644 --- a/site/CONTRIBUTING.md +++ b/site/CONTRIBUTING.md @@ -1,79 +1,25 @@ # Contributing -Thanks for your interest in contributing to the Stencil Docs! :tada: +Thanks for your interest in contributing to the Capacitor Docs! :tada: +The Capacitor website (`site/`) and documentation (`site/docs-md`) live alongside the code. Looking to assist? See Capacitor issues labeled "docs" [here](https://github.com/ionic-team/capacitor/issues?q=is%3Aopen+is%3Aissue+label%3Adocs). -## Creating an Issue +## Setup -* If you have a question about using Stencil, please ask in the [Stencil Worldwide Slack](https://join.slack.com/t/stencil-worldwide/shared_invite/enQtMjQ2MzkyMTY0MTk0LTQ4ODgzYjFjNjdkNDY3YWVhMmNlMTljMWQxNTM3Yjg0ZTIyZTM1MmU2YWE5YzNjNzE1MmQ3ZTk2NjQ1YzM5ZDM) group. - -* It is required that you clearly describe the steps necessary to reproduce the issue you are running into. Although we would love to help our users as much as possible, diagnosing issues without clear reproduction steps is extremely time-consuming and simply not sustainable. - -* The issue list of this repository is exclusively for bug reports, docs issues 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. - -* 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/stencil-site/issues/new) that thoroughly explains the problem. - -## Creating a Pull Request - -* We appreciate you taking the time to contribute! Before submitting a pull request, we ask that you please [create an issue](#creating-an-issue) that explains the bug, docs issue, or feature request and let us know that you plan on creating a pull request for it. If an issue already exists, please comment on that issue letting us know you would like to submit a pull request for it. This helps us to keep track of the pull request and make sure there isn't duplicated effort. - -* Looking for an issue to fix? Make sure to look through our issues with the [help wanted](https://github.com/ionic-team/stencil-site/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) label! - -### Setup - -1. Fork the repo. +1. Fork this 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). - - -#### Developing - -1. Run `npm run dev` +4. Run `npm install` in the `core` folder. +5. Run `npm install` in the `site` folder. +6. Run `npm run start` to build and deploy the website/docs to localhost. +> Note: Content updated while the dev server is running won't be reflected locally. Stop the process, then re-run `npm run start`. -#### Adding Documentation +## Adding a new docs page to the sidebar +Open `site/docs-md/README.md` to add the new entry to the side bar. -1. To add documentation first create a new markdown file in `docs-md` in the folder that fits your doc best. For example, if your doc is covering something in the Stencil compiler, you would put it in `docs-md/compiler`. -2. Write your documentation following the style in the other docs markdown files. Try to aim for being as clear and concise as possible. We recommend checking out the [vue.js docs](https://vuejs.org/) for examples of good docs. -3. Open `src/components/stencil-site.tsx` in your editor and add the path to your new docs markdown file but using `.html` instead of `.md` to [here](https://github.com/ionic-team/stencil-site/blob/master/src/components/stencil-site/stencil-site.tsx#L33). For example, if my new doc was located at `docs-md/basics/my-cool-doc.md` I would add `'my-cool-doc': 'basics/my-cool-doc.html',` to that object. -4. Open `src/components/site-menu.tsx` in your editor and add a new `` with the `url` attribute pointing to the path for your new doc. For example, if I just added the doc mentioned above, my path would be `basics/my-cool-doc`. -5. Run `npm run dev` to make sure your doc shows up in the menu, that you can navigate to the doc, and that your docs layout looks correct. +## Modifying documentation - -#### Modifying documentation - -1. Locate the doc you want to modify in `docs-md/`. +1. Locate the doc you want to modify in `site/docs-md/`. 2. Modify the documentation, making sure to keep the format the same as the rest of the doc. -3. Run `npm run dev` to make sure your changes look correct. - -## Commit Message Format - -We have very precise rules over how our git commit messages should be formatted. This leads to readable messages that are easy to follow when looking through the project history. - -`type(scope): subject` - -#### Type -Should be `docs` - -#### Scope -The scope can be anything specifying the place of the commit change. For example `router`, `prerendering`, etc. If you make multiple commits for the same doc, please keep the naming of this doc consistent. For example, if you make a change to the router docs and the first commit is `docs(router)`, you should continue to use `router` for any more commits related to navigation. - -#### Subject -The subject contains a succinct description of the change: - -* use the imperative, present tense: "change" not "changed" nor "changes" -* do not capitalize first letter -* do not place a period `.` at the end -* entire length of the commit message must not go over 50 characters -* describe what the commit does, not what issue it relates to or fixes -* **be brief, yet descriptive** - we should have a good understanding of what the commit does by reading the subject - - -## License - -By contributing your code to the ionic-team/stencil-site GitHub Repository, you agree to license your contribution under the MIT license. \ No newline at end of file +3. Run `npm run start` to make sure your changes look correct. From bc35797970d40afdfae2572076c775b36094ee8d Mon Sep 17 00:00:00 2001 From: Matt Netkow Date: Wed, 18 Mar 2020 13:42:13 -0500 Subject: [PATCH 2/3] update readme - fix contributing link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cd1d5842f..866e1ec3b 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Contributing to Capacitor may involve writing TypeScript, Swift/Objective-C, Jav Please read the [Contributing](.github/CONTRIBUTING.md) guide for more information. -For details on updating the Capacitor website or documentation, [see here](.github/site/CONTRIBUTING.md). +For details on updating the Capacitor website or documentation, [see here](site/CONTRIBUTING.md). [circle-badge]: https://circleci.com/gh/ionic-team/capacitor.svg?style=shield [circle-badge-url]: https://circleci.com/gh/ionic-team/capacitor From c526467ec57dec54cf602dccd507cc74a8a32656 Mon Sep 17 00:00:00 2001 From: Matt Netkow Date: Wed, 18 Mar 2020 14:06:51 -0500 Subject: [PATCH 3/3] add note about submit edit button --- site/CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/site/CONTRIBUTING.md b/site/CONTRIBUTING.md index 8ceadea32..8b5c5b727 100644 --- a/site/CONTRIBUTING.md +++ b/site/CONTRIBUTING.md @@ -20,6 +20,8 @@ Open `site/docs-md/README.md` to add the new entry to the side bar. ## Modifying documentation +For smaller edits, navigate to the desired page in the [Capacitor docs](https://capacitor.ionicframework.com/docs/) then click the "Submit an edit" button. + 1. Locate the doc you want to modify in `site/docs-md/`. 2. Modify the documentation, making sure to keep the format the same as the rest of the doc. 3. Run `npm run start` to make sure your changes look correct.