Add information about support and contribution to README

README.md

@@ -1,3 +1,34 @@
 # xk6-webcrypto
 
-This is a **work in progress** project implementation of the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) for k6.
+This is a **work in progress** project implementation of the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) specification for k6.
+
+## Current state
+
+The current state of the project is that it is an experimental, and incomplete implementation of the WebCrypto API specification. While we consider it ready for production use, it is still missing some features and is not yet fully compliant with the specification.
+
+### Supported APIs and algorithms
+
+#### Crypto
+
+- `crypto.getRandomValues()`
+- `crypto.randomUUID()`
+
+#### SubtleCrypto
+
+- `crypto.subtle.digest()` supports the complete specification's algorithms list: SHA-1, SHA-256, SHA-384, SHA-512.
+- `crypto.subtle.generateKey()` supports the following symmetric algorithms: AES-CBC, AES-GCM, and AES-CTR.
+
+### APIs and algorithms with limited support
+
+- **AES-KW**: in the current state of things, this module does not support the AES-KW (JSON Key Wrap) algorithm. The reason for it is that the Go standard library does not support it. We are looking into alternatives, but for now, this is a limitation of the module.
+- **AES-GCM**: although the algorithm is supported, and can already be used, it is not fully compliant with the specification. The reason for this is that the Go standard library only supports a 12-byte nonce/iv, while the specification allows for a wider range of sizes. We do not expect to address this limitation unless the Go standard library adds support for it.
+
+## Contributing
+
+Contributions are welcome!
+
+### Practices
+
+Contributors will likely notice that the codebase is annotated with comments of the form `// {some number}.`. Those comments are used to track the progress of the implementation of the specification. The numbers are the section numbers of the specification. For example, the comment `// 8.` in the `SubtleCrypto.GenerateKey` function refers to the [step 8 of the `generateKey` algorithm from the specification](https://www.w3.org/TR/WebCryptoAPI/#SubtleCrypto-method-generateKey).
+
+Following this convention allows us to document why certain operations are made in a certain way, and to track the progress of the implementation. We do not always add them, but we try to do so when it makes sense, and encourage contributors to do the same.