mstore/vendor/go.yaml.in/yaml/v4/CONTRIBUTING.md

Contributing to go-yaml

Thank you for your interest in contributing to go-yaml!

This document provides guidelines and instructions for contributing to this project.

Code of Conduct

By participating in this project, you agree to follow our Code of Conduct.

We expect all contributors to:

• Be respectful and inclusive
• Use welcoming and inclusive language
• Be collaborative and constructive
• Focus on what is best for both the Go and YAML communities

How to Contribute

Reporting Issues

Before submitting an issue, please:

• Check if the issue already exists in our issue tracker
• Use a clear and descriptive title
• Provide detailed steps to reproduce the issue
• Include relevant code samples and error messages
• Specify your Go version and operating system
• Use the go-yaml CLI tool described below

Using the go-yaml CLI Tool

This tool can be used to inspect both the internal stages and final results of YAML processing with the go-yaml library. It should be used when reporting most bugs.

The go-yaml CLI tool uses the go.yaml.in/yaml/v4 library to decode and encode YAML. Decoding YAML is a multi-stage process that involves tokens, events, and nodes. The go-yaml CLI tool lets you see all of these intermediate stages of the decoding process. This is crucial for understanding what go-yaml is doing internally.

The go-yaml CLI tool can be built with the make go-yaml command or installed with the go install go.yaml.in/yaml/v4/cmd/go-yaml@latest command.

You can learn about all of its options with the go-yaml -h command.

Here is an example of using it on a small piece of YAML:

./go-yaml -t <<< '
foo: &a1 bar
*a1: baz

Coding Conventions

• Follow standard Go coding conventions
• Use make fmt to format your code
• Write descriptive comments for non-obvious code
• Add tests for your work
• Keep line length to 80 characters
• Use meaningful variable and function names
• Start doc and comment sentences on a new line
• Test your changes with the go-yaml CLI tool when working on parsing logic

Commit Conventions

• No merge commits
• Commit subject line should:
  • Start with a capital letter
  • Not end with a period
  • Be no more than 50 characters

Pull Requests

1. Fork the repository
2. Create a new branch for your changes
3. Make your changes following our coding conventions
   • If you are not sure about the coding conventions, please ask
   • Look at the existing code for examples
4. Write clear commit messages
5. Update tests and documentation
6. Submit a pull request

Testing

• Ensure all tests pass with make test
• Add new tests for new functionality
• Update existing tests when modifying functionality

Development Process

• This project makes use of a GNU makefile (GNUmakefile) for many dev tasks
• The makefile doesn't use your locally installed Go commands; it auto-installs them, so that all results are deterministic
• Fork and clone the repository
• Make your changes
• Run tests, linters and formatters
  • make fmt
  • make tidy
  • make lint
  • make test
  • You can use make check to run all of the above
• Submit a Pull Request

Using Your Own Go with the Makefile

We ask that you always test with the makefile installed Go before committing, since it is deterministic and uses the exact same flow as the go-yaml CI.

We also realize that many Go devs need to run their locally installed Go commands for their development environment, and might want to use them with the go-yaml makefile.

If you need to use your own Go utils with the makefile, set GO_YAML_PATH to the directory(s) containing them (either by exporting it or passing it to make).

Something like this:

export GO_YAML_PATH=$(dirname "$(command -v go)")
make test
# or
make test GO_YAML_PATH=$(dirname "$(command -v go)")

Note: GO-VERSION and GO_YAML_PATH are mutually exclusive. When GO_YAML_PATH is set, the makefile uses your own Go environment and ignores any GO-VERSION setting.

Using the Makefile Environment as a Shell

Sometimes you might want to run your own shell commands using the same binaries that the makefile installs.

To get a subshell with this environment, run one of:

make shell
make bash
make zsh
make shell GO-VERSION=1.23.4

Makefile Targets

The repository's makefile (GNUmakefile) provides a number of useful targets:

• make test runs all tests including yaml-test-suite tests
• make test-unit runs just the unit tests
• make test-internal runs just the internal tests
• make test-yts runs just the yaml-test-suite tests
• make test v=1 count=3 runs the tests with options
• make test GO-VERSION=1.23.4 runs the tests with a specific Go version
• make test GO_YAML_PATH=/path/to/go/bin uses your own Go installation
• make shell opens a shell with the project's dependencies set up
• make shell GO-VERSION=1.23.4 opens a shell with a specific Go version
• make fmt runs golangci-lint fmt ./...
• make lint runs golangci-lint run
• make tidy runs go mod tidy
• make distclean cleans the project completely

Getting Help

If you need help, you can:

• Open an issue with your question
• Start a discussion
• Read through our documentation
• Check the migration guide if upgrading from v3
• Join our Slack channel

We are a Work in Progress

This project is very much a team effort. We are just getting things rolling and trying to get the foundations in place. There are lots of opinions and ideas about how to do things, even within the core team.

Once our process is more mature, we will likely change the rules here. We'll make the new rules as a team. For now, please stick to the rules as they are.

This project is focused on serving the needs of both the Go and YAML communities. Sometimes those needs can be in conflict, but we'll try to find common ground.

Thank You

Thank you for contributing to go-yaml!