docs: README.md & CONTRIBUTING.md

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+### Development of a new extension
+
+1. Create a separate directory under the `extensions` folder for your extension.
+2. Provide a manifest (`extension.json`) with metadata for your extension.
+3. Add your extension to `compatibility.json`, ensuring compatibility with specific `dfx` versions.
+4. Add the name of the crate of your extension to https://github.com/dfinity/dfx-extensions/blob/main/.github/workflows/release-with-github.yml under `whichCrate`, this will allow you to release new versions of your extension very easily.
+
+## How it works 
+
+The `dfx` utility offers a feature to install new extensions. This process ensures that the extensions are not only installed from a trusted source but are also compatible with the user's dfx version, enhancing the utility's reliability and user experience. Here's a high-level overview of how the installation process works:
+
+1. Determine Extension Compatibility:
+    - Before any installation can take place, `dfx` checks if the requested extension is already installed. If it is, the process terminates with an error.
+    - `dfx` identifies the version of the extension compatible with its own version. This ensures that users don't end up installing extensions that may not work properly with their specific version of `dfx`. Compatibility is determined using an extension compatibility matrix (`compatibility.json` in the root of this repository), which maps extensions to compatible versions of `dfx`.
+
+2. Download and Extraction:
+    - Once the compatible version of the extension is determined, `dfx` constructs a download URL. This URL points to a GitHub releases page where the extensions are hosted.
+    - The extension is then downloaded from this URL. 
+    - After a successful download, the extension, which is in a compressed archive format (.tar.gz), is unpacked to a temporary directory. Post extraction, the extension is renamed and moved to its permanent location (the directory where extensions are meant to reside).
+
+## Testing 
+
+### Unit testing 
+
+```console
+cargo test --workspace 
+```
+
+### End-to-end testing (e2e)
+
+1. Make sure the repository's git submodules are downloaded:
+    - When cloning the `dfx-extensions` repository:
+    ```console
+    git clone --recursive https://github.com/dfinity/dfx-extensions
+    ```
+    - If you have already cloned the `dfx-extensions` repository:
+    ```console
+    cd dfx-extensions
+    git submodule update --init --recursive
+    ```
+
+2. Run e2e tests:
+   ```console
+   e2e/bats/bin/bats extensions/**/e2e/**/*.bash
+   ```
+
+## Release a new version of the extension
+Once your changes are on the `main` branch and you wish to release a new version of the extension, the process consists of the following steps:
+1. Create a new GitHub Release with the extension's binaries. The whole process is automated using GitHub Actions. Go to https://github.com/dfinity/dfx-extensions/actions/workflows/release-with-github.yml and click `Run workflow`, then follow the instructions in the pop-up menu. Alternatively, you can trigger this workflow from your shell by navigating to the repository directory and running (in this example, we're releasing `nns` extension, version `1.2.3`):
+    ```console 
+    gh workflow run "release-with-github.yml" -f whichCrate=nns -f semverVersion=1.2.3
+    ```
+    Once the workflow finishes running, it will open a PR that you need to review and merge.
+
+2. Copy the relevant section from the extension's `CHANGELOG.md` to the description in GitHub Releases.
+
+## Styleguides
+
+### Git Commit Messages
+
+For formatting commit messages, follow the guidelines from [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).

README.md

@@ -1,2 +1,49 @@
-# DFX Extensions
-The official repository for dfx extensions.
+# DFINITY `dfx` Extensions Repository
+
+## Introduction
+Welcome to the `dfx` extensions repository by DFINITY. This repository provides essential extensions to the `dfx` command-line tool, aiming to enhance its functionality.
+
+## Features
+
+- Extend `dfx` functionality with custom commands.
+- Comprehensive end-to-end tests ensuring extensions' robustness.
+- Extensions sourced from DFINITY-reviewed code.
+- Metadata file `extension.json` for smooth user experience.
+
+## Repository Structure
+The repository has the following main directories:
+
+- **e2e:** Contains essential utilities for end-to-end testing of extensions.
+- **extensions:** Houses all the individual extensions. Currently, we have:
+  - **nns:** The NNS (Network Nervous System) extension with its configuration files, tests, commands, and source code.
+  - **sns:** The SNS (Secondary Nervous System) extension with its configuration files, tests, commands, and source code.
+- **extensions-utils:** Shared utilities for all extensions, including dependency management, error handling, logging, and project handling. You may find them useful if you're building your own extensions.
+
+Each extension in the DFINITY extensions repository has its structure:
+
+- README.md: An overview of the extension.
+- CHANGELOG.md: Tracks changes in different versions of the extension.
+- e2e: End-to-end tests and associated assets.
+- extension.json: Metadata about the extension.
+- src: Contains the Rust source code for the extension.
+
+## Getting Started
+
+### Installing/Uninstalling/Upgrading Extensions
+Head over to https://internetcomputer.org/docs/current/references/cli-reference/dfx-extension to learn more!
+
+### Extension Development
+1. Create a separate directory under the `extensions` folder for your extension.
+2. Provide a manifest (`extension.json`) with metadata for your extension.
+3. Ensure compatibility with specific `dfx` versions, which can be checked using the `compatibility.json` file.
+
+## Compatibility
+Extensions should be compatible with specific `dfx` versions. The compatibility matrix can be found in the `compatibility.json` file.
+
+## Contribution
+Contributions are welcome! If you wish to enhance an existing extension or add a new one, please follow the structure as outlined in the repository. For any significant changes, consider creating an issue or pull request.
+
+If you're looking to contribute, especially regarding releasing extensions, updating compatibility files, or any other best practices, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed guidelines.
+
+## License
+This project is licensed under the [MIT License](LICENSE).