docs: update readmes

DEVELOPER.md

@@ -1,84 +1,133 @@
 # DEVELOPER
 
-# Setting up the environment
+To build Qwik for local development, first [npm](https://docs.npmjs.com/) (or [yarn](https://yarnpkg.com/)) install the dev dependencies:
 
-## Setting up the environment
+```
+npm install
+```
 
-> NOTE: This repo is currently in the transition to the `bazel` build system. Only `bazel` developer information is documented here.
+Next the `start` command will:
 
-The repo uses `bazel` for building. Best way to run `bazel` is with [`bazelisk`](https://github.com/bazelbuild/bazelisk) which will automatically download and execute the right version of `bazel`.
+- Build the source files
+- Begin the watch process so any changes will rebuild
+- Run the type checking watch process with [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
+- Run the unit test (Jest) watch process
 
-_preferred way_
+```
+npm start
+```
+
+## Running Dev Server Integration Tests
+
+The `integration/` directory is for this local repo's end-to-end and integration testing (and not necessarily app demos). Its dev server is setup to always point to the local build and stay current with the watch process.
+
+First start the integration dev server, which will also ensure a build was completed:
 
 ```
-brew install bazelisk
+npm run integration.server
 ```
 
-or
+Then navigate to http://localhost:8080/
+
+The `npm run integration.server` comands runs the server in `development` mode, where files are not minified, source maps are inlined, and there's additional logging. To run code minified with external source maps and without extra logs, run `npm run integration.server.prod`, which is what the end-to-end tests use.
+
+## Running All Tests
+
+To run all Unit tests ([Jest](https://jestjs.io/)) and E2E/Integration tests ([Cypress](https://www.cypress.io/)), run:
 
 ```
-npm install -g @bazel/bazelisk
+npm test
 ```
 
-`Bazel` will invoke `Yarn` and manage all dependencies.
+The `test` command will also ensure a build was completed.
 
-## `bazel` vs `ibazel`
+### Unit Tests Only
 
-The difference between `bazel` and `ibazel` is that `ibazel` will re-invoke `bazel` if any relevant files change. This is useful for constantly updating the server and or tests as they are being developed. All commands are listed as `bazel`, but can be replaced for `ibazel` as needed.
+Unit tests use [Jest](https://jestjs.io/).
 
-# Running demos (`integration`)
+```
+npm run test.unit
+```
+
+To keep Jest open with the watch mode, run:
 
 ```
-bazel run integration:server
+npm run test.watch
 ```
 
-Then open:
+> Note that the `test.watch` command isn't necessary if you're running the `npm start` command, since `start` will also concurrently run the Jest watch process.
+
+To debug and step through unit tests, within VSCode you can use the "Integration Dev Server" Debug launch task.
 
-- http://localhost:8080/
+### E2E Tests Only
 
-## Running Tests
+E2E and Integration tests use [Cypress](https://www.cypress.io/).
 
-All tests:
+To run the Cypress tests headless, from start to finish, run:
 
 ```
-bazel test  //...
+npm run test.e2e
 ```
 
-### Unit tests only
+To open Cypress in interactive mode and control through a browser, run:
 
 ```
-bazel test  --test_tag_filters=unit  //...
+npm run test.e2e.open
 ```
 
-### E2e tests only
+## Production Build
 
-Before running the e2e tests, ensure that the `integration` server is running. (`bazel run integration:server`)
+The `npm start` command will run development builds, type check, watch unit tests, and watch the files for changes.
+
+A full production build will:
+
+- Builds each submodule
+- Generates bundled `.d.ts` files for each submodule with [API Extractor](https://api-extractor.com/)
+- Checks the public API hasn't changed
+- Builds a minified `core.min.mjs` file
+- Generates the publishing `package.json`
 
 ```
-bazel test  --test_tag_filters=e2e  //...
+npm run build
 ```
 
-Running cypress manually
+The build output will be written to `dist-dev/@builder.io-qwik`, which will be the directory that is published
+to [@builder.io/qwik](https://www.npmjs.com/package/@builder.io/qwik).
+
+## Publishing
+
+1. Run `npm run release`
+2. Use the [interactive UI](https://www.npmjs.com/package/np) to select the version/tag.
+3. The selected version number will become the commit message.
+4. After publishing it'll open a prefilled GitHub Releases draft.
+5. 🚀
+
+## Bazel
+
+Bazel is currently used for further testing and builds between internal repos. However, it is not required for local development and contribution to Qwik.
+
+### Setting up the Bazel environment
+
+Best way to run `bazel` is with [`bazelisk`](https://github.com/bazelbuild/bazelisk) which will automatically download and execute the right version of `bazel`.
+
+_preferred way_
 
 ```
-./node_modules/.bin/cypress open
+brew install bazelisk
 ```
 
-## Publishing
+or
 
 ```
-git fetch upstream
-git checkout main
-git reset --hard upstream/main
-# edit src/package.json wtih new version number
-VERSION=`node -e 'console.log(require("./src/package.json").version)'`
-echo "About to publish v$VERSION"
-bazel run src:pkg.publish -- --tag=latest --access=public
-git commit -a -m "release: v$VERSION"
-git tag v$VERSION
-git push upstream main:main v$VERSION
+npm install -g @bazel/bazelisk
 ```
 
+`Bazel` will invoke `Yarn` and manage all dependencies.
+
+### `bazel` vs `ibazel`
+
+The difference between `bazel` and `ibazel` is that `ibazel` will re-invoke `bazel` if any relevant files change. This is useful for constantly updating the server and or tests as they are being developed. All commands are listed as `bazel`, but can be replaced for `ibazel` as needed.
+
 ## Pre-submit hooks
 
 The project has pre-submit hooks, which ensure that your code is correctly formatted. You can run them manually like so:

README.md

@@ -4,8 +4,6 @@
   <img alt="Qwik Logo" width="400" src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F667ab6c2283d4c4d878fb9083aacc10f" />
 </p>
 
-<br />
-
 # `Qwik` DOM-Centric, Resumable Web-App Framework
 
 An Open-Source framework designed for best possible [time to interactive](https://web.dev/interactive/), by focusing on [resumability](https://github.com/BuilderIO/qwik/blob/main/docs/RESUMABLE.md) of server-side-rendering of HTML, and [fine-grained lazy-loading](https://github.com/BuilderIO/qwik/blob/main/docs/LAZY_LOADING.md) of code.
@@ -22,11 +20,17 @@ An Open-Source framework designed for best possible [time to interactive](https:
 - [A first look at Qwik - the HTML first framework](https://dev.to/mhevery/a-first-look-at-qwik-the-html-first-framework-af)
 - [Death by Closure (and how Qwik solves it)](https://dev.to/mhevery/death-by-closure-and-how-qwik-solves-it-44jj)
 
+## Development
+
+- See [Developer.md](https://github.com/BuilderIO/qwik/blob/main/DEVELOPER.md) for more information on how to build Qwik from the source and contribute!
+
 ## Community
 
-Join our [discord](https://discord.gg/JHVpZmqSs4) community.
+- Ping us at [@QwikDev](https://twitter.com/QwikDev)
+- Join our [Discord](https://discord.gg/JHVpZmqSs4) community.
+
+---
 
-<hr />
 <p align="center">
   Made with ❤️ by <a target="_blank" href="https://www.builder.io/">Builder.io</a>
 </p>