Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
153 lines (111 loc) · 7.63 KB

CONTRIBUTING.md

File metadata and controls

153 lines (111 loc) · 7.63 KB
Raw

Contributing

AI-Assistance

AI-assisted tools (e.g., code generation or language models) may be used in the course of contributing issues and pull requests. However, all contributions must meet the same standards as entirely human-written work and the use of AI should ideally be imperceptible. You remain fully responsible for correctness, maintainability, security, style, and licensing compliance. You may mention the tool or model that you used in your issue/PR description, but do not include it in the Co-authored-by or Signed-off-by commit trailer.

AI assistance may be used when drafting issues, proposals, or discussion posts, but a human must remain fully in the loop and all AI-generated content must be reviewed, fact-checked, and edited before submission. Ensure your prompts steer it to remove unnecessary fluff, verbosity, filler and irrelevant content.

If you open a pull request you must be able to clearly explain what your changes do and how they alter the behaviour of the SDK without relying upon AI tools or prompting to roundtrip the reviewer's questions. If you cannot confidently explain and defend your contribution during review, do not submit it until you can. Submissions must be readable, consistent with the existing codebase, and free of fabricated APIs, references, or unnecessary complexity.

Reporting issues

Please make sure to include any potentially useful information in the issue, so we can pinpoint the issue faster without going back and forth.

  • What SHA of the SDK are you running? If this is not the latest SHA on the main branch, please try if the problem persists with the latest version.
  • You can enable debug logging in the SDK clients to capture detailed API interactions. Please include relevant debug output in your issue description.
  • Also look at the logs of the HMC or SVC system you are connected to. If you see anything out of the ordinary, please include it.

Also, please include the following information about your environment, so we can help you faster:

  • What version of the HMC or SVC firmware are you using?
  • What version of Go are you using?
  • What are the values of your client configuration?
  • What is your operating system and architecture?

Contributing a change

Contributions to this project are released to the public under the project's opensource license. By contributing to this project you agree to the Developer Certificate of Origin (DCO). The DCO was created by the Linux Kernel community and is a simple statement that you, as a contributor, wrote or otherwise have the legal right to contribute those changes.

Contributors must sign-off that they adhere to these requirements by adding a Signed-off-by line to all commit messages with an email address that matches the commit author:

feat(phmc): add support for SR-IOV adapter management

Signed-off-by: Random J Developer <random@developer.example.org>

Git even has a -s command line option to append this automatically to your commit message:

$ git commit -s -m 'feat(phmc): add support for SR-IOV adapter management'

Because these SDKs are in production use by many people and applications, we code review all additions. To make the review process go as smooth as possible, please consider the following.

  • If you plan to work on something major, please open an issue to discuss the design first.
  • Don't break backwards compatibility. If you really have to, open an issue to discuss this first.
  • Make sure to use the go fmt command to format your code according to the standards. Even better, set up your editor to do this for you when saving.
  • Run go vet to detect any suspicious constructs in your code that could be bugs.
  • Explicitly handle all error return values. If you really want to ignore an error value, you can assign it to _. You can use errcheck to verify whether you have handled all errors.
  • You may also want to run golint as well to detect style problems.
  • Add tests that cover the changes you made. Make sure to run go test with the -race argument to test for race conditions.
  • Make sure your code is supported by all the Go versions we support (Go 1.23.0+). You can rely on GitHub Actions for testing older Go versions.
  • Document all exported functions, types, and constants with clear godoc comments.
  • Add example programs in the examples/ directory demonstrating new functionality.

Submitting a pull request

  1. Fork and clone the repository
  2. Create a new branch: git checkout -b my-branch-name
  3. Make your change, push to your fork and submit a pull request
  4. Wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
  • Write a good commit message. Use conventional commit format: type(scope): description
    • Types: feat, fix, docs, style, refactor, test, chore
    • Scopes: phmc, svc, hmcctl, infractl, pvcctl, etc.
  • Update relevant documentation (README files, godoc comments, examples).
  • Ensure all tests pass and add new tests for new functionality.

Project-Specific Guidelines

For infra-go-sdk (phmc/svc)

  • Follow the existing API patterns and naming conventions
  • Use context.Context as the first parameter for all API calls
  • Return errors with proper context using fmt.Errorf with %w
  • Add comprehensive godoc comments for all exported functions
  • Include example programs demonstrating new features
  • Test against real HMC/SVC systems when possible

For CLI tools (hmcctl/infractl/pvcctl)

  • Use the Cobra framework for command structure
  • Provide clear help text and usage examples
  • Support both flags and environment variables for configuration
  • Use structured logging with appropriate log levels
  • Handle errors gracefully with user-friendly messages
  • Update README with new command documentation

Testing

Unit Tests

# Run tests for a specific package
cd infra-go-sdk/phmc
go test ./...

# Run with coverage
go test -cover ./...

# Run with race detection
go test -race ./...

Integration Tests

Integration tests require access to real HMC or SVC systems. Mark integration tests with build tags:

//go:build integration

Run integration tests:

go test -tags=integration ./...

Code Style

  • Follow Effective Go
  • Follow Go Code Review Comments
  • Use gofmt or goimports for formatting
  • Keep functions focused and small
  • Use descriptive variable names for exported APIs
  • Use short variable names for local scope

Further Reading