Thank you for your interest in contributing to ethernetipctl! This document covers the guidelines for contributing.
- Fork the repository on GitHub
- Clone your fork locally:
git clone git@github.com:<your-username>/ethernetipctl.git cd ethernetipctl
- Create a feature branch:
git checkout -b feature/my-change
- Go 1.26+ (see go.mod)
- staticcheck, golangci-lint and govulncheck for the checks
- No hardware: the test suite brings its own devices (see Testing)
# Run all checks (format, lint, vet, 32-bit typecheck, vulnerability scan, race tests, coverage gate)
make check
# Run tests with the race detector
make test
# Run tests with whole-module coverage (fails below 90%)
make coverage
# Build for the current platform (./bin/ethernetipctl); runs `make check` first
make buildRun make (or make help) for the full list of targets.
- Follow standard Go conventions (
gofmt,go vet) - Keep functions focused and small
- Use meaningful variable and function names
- Add comments only where the logic isn't self-evident; comments end with a period (enforced by the linter)
- Classify every failure: an error that reaches the user is an
*errs.Errorwith a kind and a stable code (internal/errs,eip.WrapError). A new code is part of the contract: add it to docs/exitcodes.md - Protocol logic belongs in go-ethernetip: the CLI parses flags, calls the library and renders results. If the library lacks something, add it there
- A command that changes a device needs
--yes, validated before any connection is opened, and--yesnever has an environment variable
make fmt formats with the gofmt of the Go version in go.mod, which is the version CI uses, not necessarily the one you have installed. make fmt-check (part of make check) fails if either that gofmt or your local one would change a file: gofmt output differs slightly between Go releases, and a file the two disagree on fails CI. If they disagree, restructure the code (for example, move trailing comments onto their own lines) rather than picking a side.
Use clear, concise commit messages:
component: short description
Optional longer explanation of the change, why it was made,
and any relevant context.
Examples:
io: write only changed samples with --changesread: decode STRING2 valuesdocs: document the adapter model
- Add tests for new functionality in the appropriate
_test.gofile - Anything that talks to a device runs against a real go-ethernetip server on a free loopback port:
startFixtureincmd/helper_test.goserves OpENer's sample assemblies, an output echoed to the input, a Logix tag database, and counts sessions and requests (which proves that a change without--yessends nothing). Command tests run the real command tree throughcmd.Runand assert on stdout, stderr and the exit code - The JSON output of representative commands is pinned by golden files in
cmd/testdata/golden; after an intended change, regenerate them withgo test ./cmd -run TestGoldenJSON -updateand review the diff - A test whose prerequisite this machine may lack skips, and the skip message names its switch: with the switch set to
1the test fails instead.ETHERNETIPCTL_REQUIRE_UDP=1covers the tests that need the fixture's UDP port (discover, the discover flood, interruptingio), which the server leaves out when another socket holds it;ETHERNETIPCTL_REQUIRE_FIFO=1covers the endless-input tests that needmkfifo. The per-package coverage job in CI sets both. Platform skips (/dev/fulloff Linux, file modes on Windows) and-shorthave no switch make e2ebuilds the binary and runs the suite ine2e/(build tage2e) against it:main, exit codes and signals. CI runs it with the other jobs ofci.yml- Assert behaviour (output, exit code, the device's data), not just that the code ran
- Tests must not write files into the repository: use
t.TempDir() - Do not assume timing a device does not promise: wait for a condition with a deadline (
eventually) instead of sleeping - Keep tests fast and race-clean; CI runs them with
-race - Whole-module statement coverage must stay at or above 90% (
make coverage) - If your change affects what goes on the wire, verify against a real device or another stack when possible (OpENer, or the containers of ethernetip-interop), and say in the pull request what you tested against
When you change commands, flags, output or exit codes, update:
- The command's
Short/Long/Examplehelp text - README.md, including the environment variable table for new flags
- docs/commands.md, the flag reference of every command (from
--help;make docs-checkfails on an undocumented flag) - docs/json-output.md and docs/exitcodes.md —
--format jsonand exit codes are a stable contract for scripts - docs/adapter-config.md and testdata/adapter.yaml when the adapter model changes
- RELEASE.md, calling out anything that breaks existing usage: a
## vX.Y.Zsection at the top, with**Date:**and**Previous release:**lines, ending with a---line. The release workflow publishes the text from## <tag>to the next---as the release notes, so there is never an Unreleased section
- Push your branch to your fork:
git push origin feature/my-change
- Open a Pull Request against the
mainbranch - Describe what your change does and why
- Reference any related issues
For larger changes, please open an issue first to discuss the approach.
- Use GitHub Issues to report bugs or suggest features
- Include the output of
ethernetipctl versionin bug reports - Provide the exact command that triggered the issue, along with the error output;
--debugadds go-ethernetip's protocol log - Mention the device (vendor, product, firmware revision:
ethernetipctl identifyshows them) and whether a route or a Class 3 connection was used - Report security vulnerabilities privately: see SECURITY.md
cmd/ Root command, version, completion, Run
cmd/device/ Commands on one device (discover, identify, status, services, interfaces, read, write, objects, object, reset, session, forward-open, forward-close, connections, io, assembly, diagnose)
cmd/tag/ Rockwell Logix tag commands
cmd/eds/ EDS commands
cmd/adapter/ Simulated adapter
internal/eip/ What the commands do with go-ethernetip, error classification
internal/adapter/ The adapter model and server
internal/config/ Configuration types, flag and environment binding, host parsing
internal/format/ Output formatting (text, JSON, table, streaming)
internal/types/ Output data models
internal/runner/ Command wiring, formatted and streaming runs, fatal rendering
internal/errs/ Typed errors, stable codes, exit-code mapping
internal/cli/ Shared Cobra helpers
docs/ Exit codes, JSON output contract, adapter model reference
By contributing to ethernetipctl, you agree that your contributions will be licensed under the MIT License.
| Event | Workflow | What runs |
|---|---|---|
| Pull request | pr.yml |
docs.yml (docsync, otfabric-policy) always; ci.yml unless every changed file is documentation; then OT Fabric Required Checks |
| Push to a branch | none | nothing; dispatch ci.yml to test a branch without a pull request |
Push to main |
docs.yml |
the light checks; the merged commit was tested as the pull request's merge commit |
| Release | release.yml |
the release workflow tests the release commit again |
Documentation means an added or modified *.md file outside .github/, testdata/ and vendor/, other than AGENTS.md and CLAUDE.md. A deleted or renamed document, or any other file, runs everything. OT Fabric Required Checks fails unless every job that applies succeeded; its summary lists them.