# Contributing

Guidelines for contributing to the Armchain protocol, documentation, and ecosystem.

## Repositories

| Repository          | Description                     | Language                      |
| ------------------- | ------------------------------- | ----------------------------- |
| `armchain-client`   | Node client (armnode binary)    | Go                            |
| `armchain-ethersv6` | Ethers.js v6 fork with ML-DSA44 | TypeScript                    |
| `armchain-wallet`   | Browser extension wallet        | TypeScript                    |
| `armchain-explorer` | Block explorer                  | JavaScript (Vue.js + Node.js) |

## How to Contribute

### Reporting Issues

1. Search existing issues to avoid duplicates
2. Open a new issue with:
   * **Summary**: What happened
   * **Steps to reproduce**: How to trigger the issue
   * **Expected behavior**: What should happen
   * **Actual behavior**: What actually happens
   * **Environment**: OS, node version, SDK version, etc.

### Submitting Code

1. **Fork** the repository
2. **Create a branch** from `main`:

   ```bash
   git checkout -b feature/your-feature
   ```
3. **Make changes** following the coding standards below
4. **Write tests**, since all new features must include tests
5. **Run the test suite** and make sure all tests pass
6. **Commit** with clear, descriptive messages:

   ```
   feat: add support for batch transaction signing
   fix: correct nonce handling in HD derivation
   docs: update PQC transaction format documentation
   ```
7. **Push** and open a **Pull Request**

### Commit Message Format

We follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <description>

[optional body]
[optional footer]
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`

## Coding Standards

### Go (armchain-client)

* Follow standard Go conventions (`gofmt`, `go vet`)
* Write table-driven tests
* Document exported functions and types
* Keep functions focused and small
* Handle all errors explicitly

### TypeScript (ethersv6, wallet)

* Use TypeScript strict mode
* Follow the existing code style (ESLint configuration)
* write unit tests for new functions
* Document public APIs with JSDoc comments

### Solidity (contracts)

* Use Solidity `^0.8.x`
* Follow the [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html)
* Write comprehensive Hardhat tests
* Document with NatSpec comments

## Testing

### armchain-client

```bash
cd armchain-client
make test
```

### armchain-ethersv6

```bash
cd armchain-ethersv6
npm test
```

### Smart Contracts

```bash
npx hardhat test
```

## Documentation Contributions

This documentation lives in the `dev-docs/` directory. To contribute:

1. Fork the repository
2. Edit or create Markdown files
3. Follow the existing structure and formatting
4. Keep language clear and concise
5. Include code examples where helpful
6. Submit a PR

### Documentation Style

* Use **second person** ("you") when addressing the reader
* Use **present tense** ("The function returns..." not "The function will return...")
* Keep sentences short and direct
* Use code blocks with language hints (` ```javascript `, ` ```bash `, etc.)
* Link to related pages within the docs
* Include practical examples over theoretical explanations

## Code of Conduct

* Be respectful and constructive
* Welcome newcomers
* Focus on technical merit
* No harassment, discrimination, or personal attacks

## Getting Help

* **GitHub Issues** for bug reports and feature requests
* **Discord** for real-time discussion and support
* **Documentation**: You're reading it!

## License

Contributions are subject to the repository's license. By submitting a PR, you agree that your contributions will be licensed under the same terms.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.armchain.org/resources/contributing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.