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: ```bash ./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 1. Create a new branch for your changes 1. 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 1. Write clear commit messages 1. Update tests and documentation 1. 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](https://github.com/yaml/go-yaml/pulls) ### 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: ```bash 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: ```bash 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](https://github.com/yaml/go-yaml/issues) with your question - Start a [discussion](https://github.com/yaml/go-yaml/discussions) - Read through our [documentation](https://pkg.go.dev/go.yaml.in/yaml/v4) - Check the [migration guide](docs/v3-to-v4-migration.md) if upgrading from v3 - Join our [Slack channel](https://cloud-native.slack.com/archives/C08PPAT8PS7) ## 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!