node/CONTRIBUTING.md

# Contributing to Lux Node

Thank you for your interest in contributing to Lux Node! This document provides guidelines and instructions for contributing to the project.

To start developing on Lux Node, you'll need a few things installed.

- Golang version >= 1.26.3
- gcc
- g++

On MacOS, a modern version of bash is required (e.g. via [homebrew](https://brew.sh/) with `brew install bash`). The version installed by default is not compatible with Lux Node's [shell scripts](scripts).

## Running tasks

This repo uses the [Task](https://taskfile.dev/) task runner to simplify usage and discoverability of development tasks. To list available tasks:

```bash
./scripts/run_task.sh
```

## Issues

We are committed to fostering a welcoming and inclusive community. Please be respectful and considerate in all interactions.

- Do not open up a GitHub issue if it relates to a security vulnerability in Lux Node, and instead refer to our [security policy](./SECURITY.md).

- Use welcoming and inclusive language
- Be respectful of differing viewpoints and experiences
- Gracefully accept constructive criticism
- Focus on what is best for the community
- Show empathy towards other community members

## Getting Started

### Prerequisites

- Go 1.26.3 or higher
- Git
- Make
- GCC/G++ compiler

### Setting Up Your Development Environment

- If you want to start a discussion about the development of a new feature or the modification of an existing one, start a thread under GitHub [discussions](https://github.com/luxfi/node/discussions/categories/ideas).
- Post a thread about your idea and why it should be added to Lux Node.
- Don't start working on a pull request until you've received positive feedback from the maintainers.

2. **Clone your fork**
   ```bash
   git clone https://github.com/YOUR_USERNAME/node.git
   cd node
   ```

3. **Add upstream remote**
   ```bash
   git remote add upstream https://github.com/luxfi/node.git
   ```

4. **Install dependencies**
   ```bash
   go mod download
   ```

5. **Build the project**
   ```bash
   ./scripts/build.sh
   ```

```sh
./scripts/run_task.sh generate-protobuf
```

#### Autogenerated mocks

💁 The general direction is to **reduce** usage of mocks, so use the following with moderation.

Mocks are auto-generated using [mockgen](https://pkg.go.dev/go.uber.org/mock/mockgen) and `//go:generate` commands in the code.

- To **re-generate all mocks**, use the command below from the root of the project:

    ```sh
    ./scripts/run_task.sh generate-mocks
    ```

- To **add** an interface that needs a corresponding mock generated:
  - if the file `mocks_generate_test.go` exists in the package where the interface is located, either:
    - modify its `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface (preferred); or
    - add another `//go:generate go run go.uber.org/mock/mockgen` to generate a mock for your interface according to specific mock generation settings
  - if the file `mocks_generate_test.go` does not exist in the package where the interface is located, create it with content (adapt as needed):

    ```go
    // Copyright (C) 2019-2025, Lux Industries, Inc. All rights reserved.
    // See the file LICENSE for licensing terms.

    package mypackage

    //go:generate go run go.uber.org/mock/mockgen -package=${GOPACKAGE} -destination=mocks_test.go . YourInterface
    ```

    Notes:
    1. Ideally generate all mocks to `mocks_test.go` for the package you need to use the mocks for and do not export mocks to other packages. This reduces package dependencies, reduces production code pollution and forces to have locally defined narrow interfaces.
    1. Prefer using reflect mode to generate mocks than source mode, unless you need a mock for an unexported interface, which should be rare.
- To **remove** an interface from having a corresponding mock generated:
  1. Edit the `mocks_generate_test.go` file in the directory where the interface is defined
  1. If the `//go:generate` mockgen command line:
      - generates a mock file for multiple interfaces, remove your interface from the line
      - generates a mock file only for the interface, remove the entire line. If the file is empty, remove `mocks_generate_test.go` as well.

## Pull Request Process

### Before Submitting

- [ ] Code compiles without warnings
- [ ] All tests pass
- [ ] New tests added for new functionality
- [ ] Documentation updated if needed
- [ ] Code follows project style guidelines

```sh
./scripts/run_task.sh build
```

## Coding Standards

```sh
./scripts/run_task.sh test-unit
```

### Running Tests

```sh
./scipts/run_task.sh lint
```

## Security

### Reporting Vulnerabilities

**DO NOT** create public issues for security vulnerabilities.

Email security@lux.network with:
- Description of the vulnerability
- Steps to reproduce
- Potential impact

- Ask any question about Lux Node under GitHub [discussions](https://github.com/luxfi/node/discussions/categories/q-a).

- [Discord Community](https://discord.gg/lux)
- [GitHub Discussions](https://github.com/luxfi/node/discussions)
- [Documentation](https://docs.lux.network)

## License

By contributing, you agree that your contributions will be licensed under the project's BSD 3-Clause License.