update contributing guide and docs

CONTRIBUTING.md

@@ -2,23 +2,23 @@
 
 PRs and issues are always welcome! We appreciate your interest in Electrode and offer to help.
 
-There are [few guidelines](#contributing-guidelines) that we request contributors to follow so that we can keep things well maintained.
+There are [few guidelines](#contributing-guidelines) that we request contributors to follow.
 
 ## Getting Started
 
-This repo uses [Lerna] as a top level setup and [fyn] to manage Node Modules.
+This repo uses a custom [Lerna] mono-repo setup with [fyn] as package manager to install and local linking node modules.
 
 ### Setup
 
-Install these CLI tools globally: [xclap-cli] and [fyn]
+Install some CLI tools globally for convenience:
 
 ```bash
 $ npm install -g xclap-cli @xarc/run-cli fyn
-$ fyn -V
-0.2.41
+$ fyn -v
+0.2.47
 ```
 
-> Make sure `fyn`'s version is at least `0.2.41`
+> Make sure `fyn`'s version is at least `0.2.47`
 
 Fork and clone the repo at <https://github.com/electrode-io/electrode.git> and bootstrap all the packages.
 
@@ -31,57 +31,48 @@ $ fun bootstrap # run npm script bootstrap
 
 ### Quick Test
 
-Because many of our modules depend on each other, to make local development easier, we use [fyn] to install packages when doing development.
+This is a mono-repo and we use [fyn] to install and local linking packages when doing development. You can use `npm run`, but never use `npm install` in our repo else things will break. Below, `fun` is an alias for `npm run` that [fyn] provides.
 
 #### Try a sample
 
-Now you can go to the `samples` folder and try the `universal-react-node` sample app, develop and test your changes over there.
+Now you can go to the `samples` folder and try the `create-app-demo` sample app, develop and test your changes over there. This is the exact same app that our create-app package generates.
 
 ```bash
-$ cd samples/poc-subapp
+$ cd samples/create-app-demo
 $ fyn
 $ fun dev
 ```
 
-After running above, you should see a similar text as `Hapi.js server running at http://localhost:3000` in command line.
+After running above, you should see some output in the console with `[DEV ADMIN]`. You can press `M` for the dev menu.
 
-And when you open the browser at `http://localhost:3000`, you should see a large Electrode icon with a few demonstration components.
+And when you open the browser at `http://localhost:3000`, you should see the demo web page.
 
-### **Important** Notes
+### **Useful** Notes
 
-**Bootstrapping**
-
-- You must bootstrap the entire repo at the top dir at least once with `clap bootstrap`
-- Every time you pull down new changes or switch a branch, you should run bootstrap again.
-- Every time you make changes to a package that another depends on, you must bootstrap them again.
-- You can bootstrap a single package only: ie: `npx fynpo bootstrap --only @xarc/app-dev`
-  - This will ensure all its locally dependent packages are bootstrapped also.
+- You should bootstrap the entire repo at the top dir at least once with `xrun bootstrap`
+- After you make changes to any module under packages, if you want to test them in one of the samples, just run [fyn] in that sample and it will ensure all changed local packages are properly rebuilt.
 
 #### Test with `@xarc/create-app`
 
 You can quickly use the `xarc-create-app` package to create an app for testing.
 
 ```bash
-$ clap packages/xarc-create-app
-$ node src test-app
-$ cd test-app
+$ cd samples
+$ node ../packages/xarc-create-app/src my-test-app
+$ cd my-test-app
 $ fyn
 $ fun dev
 ```
 
-This sample app is using [fyn] to directly linked to the modules under the `packages` directory. Changes made there will be reflected in the app immediately. This is the typical testing and developing flow we use.
-
 ## Contributing Guidelines
 
 ### Submitting Pull Request
 
-We love PRs and appreciate any help you can offer. Please follow the guidelines on styling and commit messages here.
+We appreciate any help you can offer. Please follow the guidelines on styling and commit messages here.
 
 #### Styling
 
-We've now switched to use [prettier] to format all our code.
-
-Our [prettier] settings are: `--print-width 100`
+We are using [prettier] to format all our code with only one custom setting: `--print-width 100`. We are switching to version 2.
 
 > If you are making changes to a file that has not been updated yet, please commit the format first before making your changes.
 
@@ -103,69 +94,45 @@ Since we use independent lerna mode, to help keep the changelog clear, please fo
 A sample commit and PR message should look like:
 
 ```text
-[minor][feat] implement SSR support for Inferno
+[minor][feat] implement support for react-query
 ```
 
-> Note: Branching is recommended on Publish commits only so it's possible to rely on lerna to publish from that branch.
-
 ### Filing Issues
 
-We love to hear about your experience using Electrode and bug reports. Electrode has many features and it's hard for us to test everything under all scenarios and setup, so your help is very important to us.
-
-When you submit a bug report, please include the following information:
-
-- NodeJS/npm versions by doing `nodev -v` and `npm -v`
-- Your OS and version
-- Electrode package versions
-- Any errors output
-- If possible, sample code and steps on how to reproduce the bug
+If you need help or found an issue, please [submit a github issue](https://github.com/electrode-io/electrode/issues/new/choose).
 
 ## Updating Docs
 
-This repo has a [gitbook] documentation under `docs`. To review the docs as a gitbook locally:
-
-- Install [gitbook-cli] and the plugins for docs.
-- Note that gitbook (3.2.3) uses npm (3.9.2) to manage its own plugins and that may conflict with [fyn] installed `node_modules`.
-  - which is why for the top level dir of our lerna repo, we use `npm install` directly.
+Our docs use [docusaurus]. The source is in the directory `/docusaurus`. It's generated to `/docs` and published as github docs at <https://www.electrode.io/electrode>.
 
-```bash
-$ cd electrode
-$ npm install gitbook-cli -g
-$ gitbook install
-```
-
-- Now serve the book locally
+To edit the docs:
 
 ```bash
-$ gitbook serve --no-watch --no-live
+$ cd docusaurus
+$ fyn
+$ fun start
 ```
 
-And open your browser to `http://localhost:4000` to view the docs.
-
-Here is the documentation on a [gitbook] structure: <https://toolchain.gitbook.com/structure.html>
-
-> Without the `--no-watch --no-live` options it becomes unusably slow on my machine.\
-> If things don't work, then remove `~/.gitbook` and run `gitbook install` or `gitbook fetch` to let it reset itself.
+And open your browser to `http://localhost:4000` to view the docs locally.
 
 ## Releasing
 
 The versioning of modules in the this repo are all automatically controlled by the commit message.
 
 It's important that commits are isolated for the package they affected only and contains the version tags `[major]`, `[minor]`, or `[patch]`. `[patch]` is the default if tag is not found in commit message.
 
-To release, there are three steps:
+To release, follow these steps:
 
-1. Use `clap update-changelog` to detect packages that changed and their version bumps.
+1. Use `xrun update-changelog` to detect packages that changed and their version bumps.
 1. Verify and check the file `CHANGELOG.md`, add a summary of key changes under the date.
 1. Amend the commit for `CHANGELOG.md` with summary changes.
 1. Run `npx fynpo prepare --no-tag` to prepare packages for release.
-1. Run `git tag -a rel-v<#>-<date>` where `<#>` is the major archetype version, and `<date>` as `MMDDYYYY`.
-1. Publish the packages that `fynpo prepare` shown that has updates.
-1. Push release commits.
+1. Run `git tag -a rel-v<#>-<date>` where `<#>` is the major archetype version, and `<date>` as `YYYYMMDD`. (ie: `rel-v9-20210301`)
+1. Publish the packages that has version bumps.
+1. Push the release commits.
 
-[gitbook-cli]: https://www.npmjs.com/package/gitbook-cli
 [prettier]: https://www.npmjs.com/package/prettier
 [lerna]: https://lernajs.io/
-[gitbook]: https://www.gitbook.com
 [xclap-cli]: https://www.npmjs.com/package/xclap-cli
 [fyn]: https://www.npmjs.com/package/fyn
+[docusaurus]: https://docusaurus.io/

README.md

@@ -6,13 +6,14 @@
 
 # Web Applications with node.js and React
 
-Electrode was developed to make node.js and React.js a primary tech choice for developing applications at Walmart. It has been powering the <http://www.walmart.com> eCommerce website since 2017.
+The Electrode project was developed to make [node.js] and [React] the primary tech choices for developing applications at Walmart. It has been powering the <http://www.walmart.com> eCommerce website since 2017.
 
-Electrode Web is a rapid application development framework; a full stack, end-to-end platform for developing, deploying, and maintaining JavaScript applications at Walmart.
+Originally designed for Walmart specific use cases, we open-sourced part of Electrode with the hope that it will be useful to some of you in the JavaScript community. This is the same version that is used to power many applications at Walmart.
 
-Originally designed for Walmart-specific use cases, we decided to open-source electrode with the hope that it will be useful to developers in the JavaScript community.
+What we open-sourced here is the web application development part of Electrode. It focuses on building web apps with the following emphases:
 
-This is the same version that is used to power many web applications at Walmart.
+- large scale micro-frontend architecture
+- universal webapp with server side rendering powered by [node.js]
 
 # Getting Started
 
@@ -22,7 +23,7 @@ Please go to our [docs](https://www.electrode.io/electrode/docs/getting-started)
 
 # Contributing
 
-Do you find Electrode useful for your application development, or learning node.js or React? Please send us your encouragement with a github star.
+Do you find Electrode useful for your application development, exploring, or learning [node.js] and [React]? Please send us your encouragement with a github star.
 
 Did you find an issue? Would you like to help with the project? Please see our [contributing guide] for instructions on [submitting a PR] or [reporting an issue].
 
@@ -33,7 +34,8 @@ Copyright (c) 2016-present, Walmart
 Licensed under the [Apache License, Version 2.0]
 
 [apache license, version 2.0]: https://www.apache.org/licenses/LICENSE-2.0
-[node.js]: https://nodejs.org/en/download
+[node.js]: https://nodejs.org/
 [submitting a pr]: https://github.com/electrode-io/electrode/pulls
 [reporting an issue]: https://github.com/electrode-io/electrode/issues
 [contributing guide]: CONTRIBUTING.md
+[react]: https://reactjs.org/

docusaurus/docs/getting-started.md

@@ -44,7 +44,7 @@ Created react/node webapp in directory 'my-app'
 
 Your new electrode app will appear as shown below.
 
-![Hello from Electrode](/electrode/img/electrode-first-run.png)
+![Hello from Electrode](/img/electrode-first-run.png)
 
 :::important Important: Existing electrode users
 If you are an existing electrode user, please take note of the following sections

docusaurus/docusaurus.config.js

@@ -16,7 +16,7 @@ module.exports = {
         alt: "electrode logo",
         src: "/img/electrode-io-logo.png"
       },
-      links: [
+      items: [
         {
           to: "docs/getting-started",
           label: "Getting Started",
@@ -32,18 +32,18 @@ module.exports = {
     footer: {
       style: "dark",
       links: [
-        {
-          title: "Docs",
-          items: [{}]
-        },
-        {
-          title: "Community",
-          items: [{}]
-        },
-        {
-          title: "More",
-          items: [{}]
-        }
+        // {
+        //   title: "Docs",
+        //   items: [{}]
+        // },
+        // {
+        //   title: "Community",
+        //   items: [{}]
+        // },
+        // {
+        //   title: "More",
+        //   items: [{}]
+        // }
       ],
       copyright: `Copyright © ${new Date().getFullYear()} Walmart`
     }