From e5cdccabe9cb0a0fca852112e40f3ef420a8ca7e Mon Sep 17 00:00:00 2001 From: Yuri Guller Date: Wed, 3 Jun 2020 12:49:34 +0300 Subject: [PATCH 1/2] adjusted readme to be consumer oriented, started apart a contributing guideline --- README.md | 56 ++++++++++++++++++++------------------------ docs/contributing.md | 24 +++++++++++++++++++ 2 files changed, 49 insertions(+), 31 deletions(-) create mode 100644 docs/contributing.md diff --git a/README.md b/README.md index 953563728c..da5550f964 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,32 @@ # Vivid UI components ![develop build](https://github.com/Vonage/vivid/workflows/develop%20build/badge.svg?branch=develop) -[vivid.vonage.com for demos](https://vivid.vonage.com) +Vivid provides a Design System comprised of ready-to-use web components and services, aligned with the Vonage's design guidelines, providing well-thought APIs and striving to stick to the best practices in every possible aspect. -### Roadmap +Demos, tutorials and living examples are at [vivid.vonage.com](https://vivid.vonage.com). -Vivid project is set to deliver Vonage's own design system for the company project's front-ends. +Contributor guidance is [here](docs/contributing.md). + +--- + +#### Consumption + +Our deliveries are available as GitHub packages, they are privately accessible within Vonage organization. + +Please visit [Vivid packages page](https://github.com/Vonage/vivid/packages) to enlist our latest releases. You may further drill into each package to read its specific documentation, review previous versions etc. + +GitHub packages may be consumed via various build systems, please refer to [this documentation](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem) for more details. + +Obviously, most likely Vivid products will be consumed as **npm** dependencies in **package.json**, specific documentation on that found [here](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages#installing-a-package). + +--- + +#### Roadmap The system contains these aspects: -- general services/facilities like fonts management, scheme management and alike +- general services/facilities (fonts management, scheme management etc) - atomic/generic components -- high level business specific components +- high level business-logic specific components The overall roadmap may be split into the the following: * alpha (0.0.x versions; alpha-romeo :)) - initial release (month to few months?), deliverables of this release are likely to have breaking changes @@ -58,6 +74,7 @@ The overall roadmap may be split into the the following: | `` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+radio) | | `` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/235304) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+scheme+schema+theme+select) | | `` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/235301) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+select) | +| `` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/251037) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+slider) | | `` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/235302) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+switch) | | `` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+table) | | `` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/166369) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+textfield) | @@ -71,39 +88,16 @@ The overall roadmap may be split into the the following: | `` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+dialer) | | `` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+video+player+videoplayer) | - -### Get up and running - -* Clone the repo -* Run `yarn` (repo relies on yarn workspaces) in order to build the repo once / bring the dependencies -* Run the following steps as the normal build-and-see flow: - * `yarn compile` - builds `css` from `scss`, compiles `ts` into `js` - * `yarn dev:server` - runs dev server on `localhost` in order to see the demo pages - * OR `yarn start` - is a shortcut for `compile` and `dev:server`, for your convenience - * AND `yarn watch` - observes & compiles scss / ts files in src folders. Run it in a separate terminal window in order to watch changes occur while editing files. -* Navigate to `https://localhost:5424/index.html` (replace the port if needed) and start hacking with the components in the browser -* Welcome! :) - --- - -## Scripts - -- `yarn` does initial installation of the dependencies (yarn is preferred here for a fast resolution) -- `compile` compiles typescript, scss etc -- `start` runs demo app for development (will auto trigger `compile` command beforehand), reloading on file changes -- `test` runs test suite with Karma -- `lint` runs the linter for your project -- `build` builds demo app for production - - -## Issues +#### Issues We use GitHub Issues as the official bug tracker for **Vivid** Please check the [existing issues](https://github.com/vonage/vivid/issues). It's possible someone has already reported the same problem. If your problem or idea is not addressed yet, [open a new issue](https://github.com/vonage/vivid/issues/new). +--- -## Suggestions +#### Suggestions Go through the [board](https://github.com/vonage/vivid/projects/1) to search for existing feedbacks and share yours if not already addressed. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000000..c5abee61be --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,24 @@ + +### Get up and running + +* Clone the repo +* Run `yarn` (repo relies on yarn workspaces) in order to build the repo once / bring the dependencies +* Run the following steps as the normal build-and-see flow: + * `yarn compile` - builds `css` from `scss`, compiles `ts` into `js` + * `yarn dev:server` - runs dev server on `localhost` in order to see the demo pages + * OR `yarn start` - is a shortcut for `compile` and `dev:server`, for your convenience + * AND `yarn watch` - observes & compiles scss / ts files in src folders. Run it in a separate terminal window in order to watch changes occur while editing files. +* Navigate to `https://localhost:5424/index.html` (replace the port if needed) and start hacking with the components in the browser +* Welcome! :) + +--- + + +## Scripts + +- `yarn` does initial installation of the dependencies (yarn is preferred here for a fast resolution) +- `compile` compiles typescript, scss etc +- `start` runs demo app for development (will auto trigger `compile` command beforehand), reloading on file changes +- `test` runs test suite with Karma +- `lint` runs the linter for your project +- `build` builds demo app for production \ No newline at end of file From 4e9c91ebf4190c9bb5a5eda287b787222d469873 Mon Sep 17 00:00:00 2001 From: Yuri Guller Date: Wed, 3 Jun 2020 17:43:54 +0300 Subject: [PATCH 2/2] improving docs --- README.md | 2 +- docs/contributing.md | 67 +++++++++++++++++++++++++++++++++++--------- 2 files changed, 55 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index da5550f964..e622982b01 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Please visit [Vivid packages page](https://github.com/Vonage/vivid/packages) to GitHub packages may be consumed via various build systems, please refer to [this documentation](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem) for more details. -Obviously, most likely Vivid products will be consumed as **npm** dependencies in **package.json**, specific documentation on that found [here](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages#installing-a-package). +Obviously, most likely Vivid products will be consumed as **npm** dependencies in **package.json**, specific documentation on that is located [here](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages#installing-a-package). --- diff --git a/docs/contributing.md b/docs/contributing.md index c5abee61be..05c90994f5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,24 +1,65 @@ +# Contributor guideline -### Get up and running +Vivid team is dedicated to deliver and support the services and the components for the front end teams across the Vonage. -* Clone the repo -* Run `yarn` (repo relies on yarn workspaces) in order to build the repo once / bring the dependencies -* Run the following steps as the normal build-and-see flow: +Yet, we believe that this project should be managed as an open source, within the organization. +Contributions are most welcome. + +As with any other platform-like case, responsibility for a stable and quality code for all requires some process to be followed and some reasonable gatekeepers to pass over. + +--- + +#### Process + +##### Feature request + +When a team needs some service or component which feels like suitable for a broader usage, we advise first to see an existing stuff, [packages](https://github.com/Vonage/vivid/packages) and [demo](vivid.vonage.com) are the best places to refer to. + +If the desired thing was not found, please consult with an [issues](https://github.com/Vonage/vivid/issues) and [features](https://github.com/Vonage/vivid/projects), it is possible something is already in the pipe. + +If yet nothing similar found, create a new feature request / issue. Of course, everyone is more than welcome to contact Vivid team directly too. + +Important! We do ask to follow this process even if the one is going to implement the feature her/himself. + +##### Coding time + +Have you decided to implement something cool as part of the Vivid project? Great! We'd like to help you with that so that the dev-experience would be excellent. +Below are few intos, but most important - is something doesn't feel right, please talk to us. +We won't promise that everything will be fixed as we are opinionated people as well, but we'll definitely listen carefully and try to solve things. + +###### Getting up and running + +* clone the repo +* run `yarn` (repo relies on yarn workspaces) in order to build the repo once / bring the dependencies +* run the following steps as the normal build-and-see flow: * `yarn compile` - builds `css` from `scss`, compiles `ts` into `js` * `yarn dev:server` - runs dev server on `localhost` in order to see the demo pages - * OR `yarn start` - is a shortcut for `compile` and `dev:server`, for your convenience - * AND `yarn watch` - observes & compiles scss / ts files in src folders. Run it in a separate terminal window in order to watch changes occur while editing files. -* Navigate to `https://localhost:5424/index.html` (replace the port if needed) and start hacking with the components in the browser + * OR `yarn start` - this is a shortcut for `compile` and `dev:server`, for your convenience + * `yarn watch` - watches for changes in scss / ts files in src folders and recompiles whatever is needed (run in another terminal) +* navigate to `http://localhost:5424/index.html` and start hacking with the components in the browser * Welcome! :) +* just before getting into the change, please make sure to branch out from the `develop` branch, giving your branch some good and descriptive name +* during the coding time, it is best to sync with `develop` rather frequently, we'll do our best to keep it evergreen + +###### Coded, looks okay, now quality time + +In order to ensure certain level of quality we rely on automation. +But even before you code hits the CI you can run some preliminary checks locally: +* `yarn lint` - runs the linter (ESLint) on your code (I'm always surprised how it finds typos in my best crafted code :)) +* `yarn test` - runs test suite (Karma); this one will ensure that you've not broken stuff of anyone else; but it is even better to add you own tests to the new functionality too, trust us, you'll sleep better this way :) + +> We do have a coverage collected (Istanbul) but its level is not yet enforced at this point. Full report may be found in a nice UI layout in the coverage folder after the tests ran. + +###### All good, let' deliver + +When you happy with what you've done, please open a PR back to the `develop` branch. +You may specify reviewer if relevant. + +Done! Well, there probably will be some exchange of comments and fixes, but eventually your PR will be merged into the `develop` branch, which will eventually be taken to release branch and finally pushed to production. --- -## Scripts +#### Useful scripts -- `yarn` does initial installation of the dependencies (yarn is preferred here for a fast resolution) -- `compile` compiles typescript, scss etc -- `start` runs demo app for development (will auto trigger `compile` command beforehand), reloading on file changes -- `test` runs test suite with Karma -- `lint` runs the linter for your project - `build` builds demo app for production \ No newline at end of file