UX and DX: create zkApp CLI contributing.md and use absolute links in…

… README so npm works (#443)

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+## Contributing
+
+Welcome to the Mina zkApp CLI open source repository. Thank you for being a part of the Mina ecosystem and for your interest in contributing to the Mina zkApp CLI project.
+
+SnarkyJS helps developers build apps powered by zero-knowledge (zk) cryptography. The best way to get started with SnarkyJS is to use the Mina zkApp CLI to [write a zkApp](https://docs.minaprotocol.com/zkapps/how-to-write-a-zkapp).
+
+The best way to contribute to the Mina zkApp CLI is to help us test it broadly to ensure it works as expected on all platforms.
+
+By contributing, you can help us improve the functionality and user experience of the zkApp CLI, which in turn helps you build better projects. To ensure a smooth and effective collaboration, please follow these contribution guidelines.
+
+## Code of Conduct
+
+All contributors agree to respect and follow the Mina Protocol [Code of Conduct](https://github.com/MinaProtocol/mina/blob/develop/CODE_OF_CONDUCT.md).
+
+
+## Did you find a bug?
+
+To see if others have also experienced the issue:
+
+- Ask questions in the Mina Protocol Discord in the  [#zkapps-developers](https://discord.com/channels/484437221055922177/915745847692636181) channel on Mina Protocol Discord. 
+- Participate and ask questions in [zkApps Developers Office Hours](/participate/office-hours).
+- Check if the bug was already reported by searching on GitHub under [Issues](https://github.com/o1-labs/zkapp-cli/issues).
+
+If you don't find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and the output of the `zk system` command. This information includes your OS, NodeJS, and zkapp-cli versions to help us reproduce the issue.
+
+After you open an issue, it might not see activity immediately unless it is a "Everything is on Fire and the World is Coming to an End" kind of bug. That doesn't mean we don't care about your bug, just that there are a lot of issues and pull requests to get through. Other people with the same problem can find your issue, confirm the bug, and may collaborate with you on fixing it. If you know how to fix the bug, go ahead and open a pull request.
+
+## Clone the Repository
+
+To be able to contribute code, you must clone the `zkapp-cli` repository:
+
+```sh
+git clone https://github.com/o1-labs/zkapp-cli.git
+cd zkapp-cli
+git remote add upstream https://github.com/o1-labs/zkapp-cli.git
+npm install
+npm link # makes it available globally on your system
+```
+
+If you have previously run `npm link` against a different version of `zkapp-cli` (say, after the branches switch):
+
+```sh
+npm r zkapp-cli -g && npm install && npm run build --if-present && npm link
+```
+
+The `main` branch contains the development version of the code.
+
+To create a new branch for your contributions:
+
+```sh
+git checkout -b upstream/main
+```
+
+Make your changes and commit:
+
+```sh
+git push origin <your-branch>
+```
+
+Create and submit your pull request against the `main` branch. 
+
+To switch back to the released version of zkApp CLI:
+
+```sh
+npm i -g zkapp-cli`
+```
+
+### Pull Requests (PRs)
+
+To contribute directly to this project repo, submit a PR.
+
+Provide a helpful, informative PR title that includes the context and page you are updating. Each PR must address only one issue or feature.
+
+Start by creating a draft pull request. Create your draft PR early, even if your work is just beginning or incomplete. Your draft PR indicates to the community that you're working on something and provides a space for conversations early in the development process. Merging is blocked for Draft PRs, so they provide a safe place to experiment and invite comments.
+
+All pull requests must go through the code review process. As the PR submitter, you must address each comment and suggestion in the **Files changed** view during the review process.
+
+If your PR is a fork, the code maintainers will merge the approved PR.
+
+## Docs
+
+The Mina zkApp CLI is the primary way developers build zkApps.
+
+The documentation and tutorials are the pathways to foundational knowledge. We welcome contributions to [zkApps Developer](https://docs.minaprotocol.com/zkapps) documentation. See the [Docs Contributing Guidelines](https://github.com/o1-labs/docs2/blob/main/CONTRIBUTING.md).

README.md

@@ -1,46 +1,64 @@
 # Mina zkApp CLI
 
-The Mina zkApp CLI allows you to scaffold, write, test, & deploy zkApps
-("zero-knowledge apps") for [Mina Protocol](https://minaprotocol.com/) using
-recommended best practices. Apps are written using
-[SnarkyJS](https://docs.minaprotocol.com/en/zkapps/snarkyjs-reference), a
-TypeScript framework for writing zero-knowledge proof-based smart contracts,
-which is included by default in projects created using this CLI.
+The Mina zkApp CLI allows you to scaffold, write, test, and deploy zkApps (zero knowledge apps) for [Mina Protocol](https://minaprotocol.com/) using recommended best practices. 
 
-## Getting started
+Apps are written using [SnarkyJS](https://docs.minaprotocol.com/en/zkapps/snarkyjs-reference), a TypeScript framework for writing zero knowledge proof-based smart contracts. SnarkyJS is automatically included when you create a project using the Mina zkApp CLI.
 
-To get started, please read this README, followed by [Mina Protocol's zkApp
-docs](https://docs.minaprotocol.com/zkapps) for a step-by-step guide.
+## Getting Started
 
-## Dependencies
+Read through this README file and the Mina Protocol [zkApp Developer](https://docs.minaprotocol.com/zkapps) docs. 
 
-You'll need the following installed to use the zkApp CLI:
+Build foundational knowledge by completing the guided steps in the [zkApp Developer Tutorials](https://docs.minaprotocol.com/zkapps/tutorials).
 
-- NodeJS 16+ (or 14 using `--experimental-wasm-threads`)
-- NPM 6+
-- Git 2+
+## Get Involved
 
-If you have an older version installed, we suggest installing a newer version
-using the package manager for your system: [Homebrew](https://brew.sh/) (Mac),
-[Chocolatey](https://chocolatey.org/) (Windows), or apt/yum/etc (Linux). On
-Linux, you may need to install a recent NodeJS version via NodeSource
-([deb](https://github.com/nodesource/distributions#debinstall) or
-[rpm](https://github.com/nodesource/distributions#rpminstall)), as recommended
-by the NodeJS Project.
+To learn about ways to participate and interact with community members, see the Mina [Online Communities](https://docs.minaprotocol.com/participate/online-communities) docs. 
 
-## Installation
+Contributions are always appreciated. See the zkApp CLI [CONTRIBUTING](https://github.com/o1-labs/zkapp-cli/blob/main/README.md) guidelines.
+
+## Install the Mina zkApp CLI
+
+To install the Mina zkApp CLI:
+
+```sh
+$ npm install -g zkapp-cli
+```
+
+To confirm successful installation:
 
 ```sh
-npm install -g zkapp-cli
+$ zk --version
 ```
 
+### Dependencies
+
+To use the zkApp CLI and SnarkyJS, your environment requires:
+
+- NodeJS v16 and later (or NodeJS v14 using `--experimental-wasm-threads`)
+- NPM v6 and later
+- Git v2 and later
+
+Use a package manager to install the required versions and upgrade older versions if needed. Package managers for the supported environments are:
+
+- MacOS [Homebrew](https://brew.sh/)
+- Windows [Chocolatey](https://chocolatey.org/)
+- Linux
+
+  - apt, yum, and others
+
+  On Linux, you might need to install a recent Node.js version by using NodeSource. Use [deb](https://github.com/nodesource/distributions#debinstall) or [rpm](https://github.com/nodesource/distributions#rpminstall) as recommended by the Node.js project.
+
+To verify your installed versions, use `npm -v`, `node -v`, and `git -v`.
+
 ## Usage
 
+To see all of the zkApp CLI commands:
+
 ```sh
 zk --help
 ```
 
-### Create a new project
+### Create a project
 
 ```sh
 zk project my-proj  # or path/to/my-proj
@@ -59,40 +77,26 @@ Next steps:
   git push -u origin main
 ```
 
-This command creates a directory containing a new project template, fully set up
-& ready for local development.
+This command creates a directory containing a new project template, fully set up and ready for local development.
 
 - See the included [README](templates/project-ts/README.md) for usage instructions.
-  All usual commands will be available: `npm run build`, `npm run test`,
-  `npm run coverage`, etc.
-- A Git repo will be initialized in the project directory automatically. For
-  consistency, we use `main` as the default Git branch, by convention.
-- A [Github Actions CI workflow](templates/project-ts/.github/workflows/ci.yml) is
-  also included. If you push your project to Github, Github Actions will run
-  your tests (named as `*.test.js`) automatically, whenever you push a commit or
-  open a pull request.
-- Code style consistency (via Prettier) and linting (via ES Lint) are
-  automatically enforced using Git pre-commit hooks. This requires no
-  configuration and occurs automatically when you commit to Git--e.g. `git commit -m 'feat: add awesome feature'`.
-- To skip all checks in the Git pre-commit hook (not recommended), you can pass
-  the `-n` flag to Git--e.g. `git commit -m 'a bad commit' -n`. But we'd
-  recommend avoiding this and resolving any errors which exist in your project
-  until the pre-commit hook passes.
-
-### Create an example project
+  All of the usual commands are available: `npm run build`, `npm run test`, `npm run coverage`, and so on.
+- A GitHub repo is automatically initialized in the project directory. For consistency and by convention, we use `main` as the default development branch.
+- A [GitHub Actions CI workflow](templates/project-ts/.github/workflows/ci.yml) is 
+  also included. If you push your project to GitHub, GitHub Actions run your tests (named as `*.test.js`) automatically whenever you push a commit or open a pull request.
+- Code style consistency (using Prettier) and linting (using ES Lint) is automatically enforced using Git pre-commit hooks. This requires no configuration and occurs automatically when you commit a change, for example, `git commit -m 'feat: add awesome feature'`.
+
+## Create an example project
 
 ```sh
 zk example <name>
 ```
 
-Where `name` is one of the names found in the [example directory](examples).
+where `name` is one of the names found in the [zkApps examples](https://github.com/o1-labs/docs2/tree/main/examples/zkapps) directory.
 
-All examples are based on the standard project template created by the
-zkApp CLI, and only contain changes within the `src` directory, so feel free to use
-one of these as your project base.
+All examples are based on the standard project template created by the zkApp CLI and contain only changes within the `src` directory, so feel free to use one of these examples as your project base.
 
-When inside an example folder in your terminal, you can run the example using
-the following command:
+When inside an example folder in your terminal, you can run the example:
 
 ```sh
 npm run build && node ./build/src/index.js
@@ -104,99 +108,66 @@ npm run build && node ./build/src/index.js
 zk file <name>  # or path/to/name
 ```
 
-This will create `name.js` and `name.test.js`.
+This command creates `name.js` and `name.test.js`.
+
+For convenience, when you run this command in your project's _root_ directory creates the files inside your project's `src` dir automatically, even if you don't specify `src/` as part of your file path. 
 
-For convenience, running this command in your project's _root_ directory will
-create the files inside your project's `src` dir automatically, even if you
-don't specify `src/` as part of your file path. When _not_ in your project's
-root dir, files will be created at the path you specify relative to your
-terminal's current working directory.
+When you run this command when you are _not_ in your project's
+root dir, files are created at the path you specify relative to your terminal's current working directory.
 
 ### Show system info
 
 ```sh
 zk system
 ```
 
-This will output system info such as your NodeJS version, NPM version,
-`zkapp-cli` version, etc. Please include this if submitting a bug report for
-`zkapp-cli`, for easier troubleshooting.
+This command outputs system info such as your NodeJS version, NPM version, `zkapp-cli` version, and so on. For easier troubleshooting, be sure to include this information if submitting a bug report for `zkapp-cli`. See the [CONTRIBUTING](https://github.com/o1-labs/zkapp-cli/blob/main/README.md) guidelines.
 
 ### Update your config.json
 
 ```sh
 zk config
 ```
 
-`config.json` is an auto-generated file and contains your deployment-related
-configurations.
+The auto-generated `config.json` file contains your deployment-related configurations.
 
 Run the `zk config` command to add a new deployment configuration to this file.
 
-This command is interactive and will prompt you to specify 1.) a network name
-(can be anything, e.g. `testnet`), 2.) the Mina GraphQL API URL where you want to
-send your deployment transaction (e.g.
-`https://proxy.berkeley.minaexplorer.com/graphql`), and 3.) the transaction fee
-to be used during deployment (in MINA; e.g. `0.01`). The URL is significant
-because this determines which network you're deploying to (e.g. `QANet`,
-`Testnet`, etc).
+Respond to the interactive command prompts to build or update a deploy alias. 
 
-Note: If your project contains more than one smart contract that you will be
-deploying, we recommend following an alias naming convention such as `testnet-foo`
-and `testnet-bar`, where `testnet` is the name of the network and `foo` and `bar`
-are the name of your smart contracts. Then you can deploy using `zk deploy testnet-foo` and `zk deploy testnet-bar`.
-
-### Deploy your smart contract
+A deploy alias consists of:
 
-```sh
-zk deploy <alias>
-// OR
-zk deploy // will show a list of aliases in your project to choose from
-```
+- A self-describing name. This tutorial uses `berkeley`. The deploy alias name can be anything and does not have to match the network name.
+- The Mina GraphQL API URL that defines the network that receives your deploy transaction and broadcasts it to the appropriate Mina network (Testnet, Devnet, Mainnet, and so on)
+- The transaction fee (in MINA) to use when deploying
+- Two key pairs:
 
-_**Deployment is possible to Berkeley Testnet currently. It is not possible to deploy
-to Mina Mainnet at this time.**_
+  - A key pair for the zkApp account. Public and private keys to use in your application are automatically generated in `keys/berkeley.json`.
 
-The `deploy` command allows you to deploy a smart contract to your desired
-alias. You must run `zk config` once before deploying, in order to set up a
-deploy alias with the required details. Then run `zk deploy <alias>` or `zk deploy` (and select the alias from the list shown) and type `yes` or `y` to
-confirm when prompted.
+  - A key pair to use as a fee payer account for updates and deployments. Public and private keys are stored on your local computer and can be used across multiple projects.
 
-Note: When deploying to an alias for the first time, the CLI will prompt you to
-choose which smart contract you want to deploy from those that exist as _named_
-exports in your project. The name of the smart contract that you choose will
-then be remembered by being saved into your `config.json` for this alias, so
-that running `zk deploy <alias>` will automatically deploy this _same_ smart
-contract in the future when deploying to this alias, for safety.
+- Fee payer account alias 
 
-## Contributing
+  A fee payer account is required. If you don't have a fee payer account, you are prompted to select one of these options:
 
-The best way to contribute to the zkApp CLI is to help us test it broadly to
-ensure it works as expected on all platforms. If you encounter any issues,
-please submit an issue on Github and include the info printed when running `zk system`, which contains your OS, NodeJS, & zkapp-cli versions to help us
-reproduce the issue.
+  - Recover a fee payer account from an existing base58 private key
+  - Create a new fee payer key pair
 
-To submit a PR:
+### Deploy your smart contract
 
 ```sh
-# Visit https://github.com/o1-labs/zkapp-cli & fork it.
-git clone https://github.com/<your-username>/zkapp-cli.git
-cd zkapp-cli
-git remote add upstream https://github.com/o1-labs/zkapp-cli.git
-npm install
-npm link # makes it available globally on your system
-
-# You can also use the following commands if you have previously run `npm link`
-# against the different version of `zkapp-cli` (say, after the branches switch):
-# npm r zkapp-cli -g && npm install && npm run build --if-present && npm link
-
-git checkout -b upstream/main
-# Make desired changes and commit
-git push origin <your-branch>
-# Submit a pull request
-# To switch back to the released version, run `npm i -g zkapp-cli`
+zk deploy <alias>
+// OR
+zk deploy // shows a list of aliases in your project to choose from
 ```
 
+_**Deployment is supported only to Berkeley Testnet. 
+zkApp programmability is not yet available on the Mina Mainnet.**_
+
+After you run `zk config`, the `zk deploy` command allows you to deploy a smart contract to a specified deploy alias. 
+
+Note: When you deploy to an alias for the first time, you are prompted to choose which smart contract you want to deploy from those that exist as _named_ exports in your project. The name of the smart contract that you choose is remembered by being saved into your `config.json` for this alias. For safety, the next time you run `zk deploy <alias>` this _same_ smart contract automatically deploys to this alias. See [Tutorial 3: Deploy to a Live Network](https://docs.minaprotocol.com/zkapps/tutorials/deploying-to-a-network).
+
 ## License
 
-[Apache-2.0](LICENSE)
+[Apache-2.0](https://github.com/o1-labs/zkapp-cli/blob/main/LICENSE)

package.json

@@ -1,11 +1,20 @@
 {
   "name": "zkapp-cli",
   "version": "0.10.1",
-  "description": "CLI to create a zkApp (\"zero-knowledge app\") for Mina Protocol.",
+  "description": "CLI to create zkApps (zero-knowledge apps) for Mina Protocol",
+  "homepage": "https://github.com/o1-labs/zkapp-cli/",
   "keywords": [
-    "cli",
     "mina",
+    "snarkyjs",
     "zkapp",
+    "zk",
+    "smart contract",
+    "cryptography",
+    "blockchain",
+    "web3",
+    "zk-snark",
+    "zero knowledge",
+    "cli",
     "dapp"
   ],
   "license": "Apache-2.0",