Contributing to Matterbridge
Relevant source files
The following files were used as context for generating this wiki page:
Contributing to Matterbridge involves enhancing a multi-protocol chat bridge that connects various platforms like Discord, Slack, Mattermost, and IRC. The project relies on Go (version 1.18+) and utilizes a variety of specialized libraries to manage individual protocol connections. Contributors can help by reporting bugs, improving documentation, or submitting code changes that adhere to the project's standards for stability and performance.
Sources: README.md:1-125, vendor/github.com/pelletier/go-toml/v2/CONTRIBUTING.md:4-9
Development Environment and Requirements
Matterbridge is built using the Go programming language. To compile the project from source, Go 1.18 or higher is required. The build process can be memory-intensive due to the high number of supported bridges, often requiring up to 3GB of RAM. Developers can use build tags to exclude specific bridges, such as Microsoft Teams, to reduce resource consumption during compilation.
Sources: README.md:144-152
Build Commands
The project supports various build configurations via Go tags:
| Target | Command | Description |
|---|---|---|
| Standard | go install github.com/42wim/matterbridge | Installs the latest stable version. |
| Development | go install github.com/42wim/matterbridge@master | Installs the latest version from the master branch. |
| Minimal | go install -tags nomsteams,nozulip ... | Excludes heavy bridges to save memory. |
| WhatsApp Multi | go install -tags whatsappmulti ... | Includes WhatsApp multi-device support (GPL3). |
Sources: README.md:158-185
Contribution Workflow
The project follows a standard GitHub-based contribution flow. Contributors are encouraged to search existing issues before opening new ones and to use pull requests (PRs) for code changes.
The diagram above illustrates the typical lifecycle of a contribution from identification to merging.
Sources: vendor/github.com/pelletier/go-toml/v2/CONTRIBUTING.md:56-65, vendor/github.com/minio/minio-go/v7/CONTRIBUTING.md:1-12
Pull Request Guidelines
- Atomicity: PRs should ideally contain no more than two commits; otherwise, they should be squashed.
- Documentation: New features must be documented in the README or relevant wiki sections.
- Testing: Bug fixes must include regression tests, and new features must be accompanied by unit tests.
- Style: Code must strictly conform to
go fmtstandards.
Sources: vendor/github.com/graph-gophers/graphql-go/CONTRIBUTING.md:9-15, vendor/github.com/minio/minio-go/v7/CONTRIBUTING.md:14-22
Code Standards and Architecture
Matterbridge operates as a gateway between accounts. Each account belongs to a specific protocol (e.g., slack.myteam). Messages are routed through gateways defined in a TOML configuration.
Messaging Data Model
When implementing new features or bridges, developers must interact with the standard message structures.
| Field | Type | Description |
|---|---|---|
username | string | The display name of the sender. |
text | string | The message content. |
gateway | string | The bridge gateway name. |
event | string | Specific matterbridge event type. |
extra | object | Metadata such as file attachments (base64). |
Sources: contrib/api.yaml:63-110
Naming Conventions
Contributors should follow established patterns for methods and structures to maintain consistency:
- REST Methods: Entity name followed by action (e.g.,
ChannelMessageEdit). - Event Structures: Matching gateway internal naming (e.g.,
InteractionCreate). - Returns: Favor named returns for improved readability, especially in long function bodies.
Sources: vendor/github.com/bwmarrin/discordgo/CONTRIBUTING.md:39-65
Testing and Quality Assurance
Verification is a critical part of the contribution process. All changes must pass existing CI checks, which typically include multiple Go versions and operating systems (Linux, Windows, MacOS).
Performance and Coverage
For core modules, contributors should ensure that:
- Coverage: Code coverage does not decrease. This can be checked using
go tool cover. - Performance: Changes do not introduce regressions. This is verified by running benchmarks and comparing results with
benchstat.
# Running benchmarks
go test ./... -bench=. -count=10
# Comparing results
benchstat old.txt new.txt
Sources: vendor/github.com/pelletier/go-toml/v2/CONTRIBUTING.md:86-125
Community Standards
Matterbridge maintains an open and welcoming environment. All participants are expected to adhere to the project's Code of Conduct, which prohibits harassment, personal attacks, and unprofessional behavior. Maintainers reserve the right to remove contributions or ban individuals who violate these standards.
Sources: vendor/github.com/wiggin77/srslog/CODE_OF_CONDUCT.md:1-30
Summary
Contributing to Matterbridge requires a combination of technical proficiency in Go and adherence to rigorous testing and architectural standards. By following the outlined workflow—from forking and branching to running performance benchmarks and ensuring code coverage—developers can effectively expand the bridge's capabilities while maintaining the project's stability.