211 lines
6.1 KiB
Markdown
211 lines
6.1 KiB
Markdown
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!
|