Update Go Style Guide #1
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Per internal discussion, add guidance on explicit tags on fields of structs intended to be marshaled to JSON/YAML/etc. Co-authored-by: Abhinav Gupta <mail@abhinavg.net> Co-authored-by: Matt Way <mway@users.noreply.github.com>
Methods from `ioutil` package are used in the style guide. Despite any code using them is completely valid, according to the [package documentation](https://pkg.go.dev/io/ioutil) it would be better to use similar methods from `io` and `os` packages. This substitutes these methods in the style guide.
This adds a small note in the Introduction section about the sample Go code used in this guide are based on latest two versions of Go.
In general, we prefer for goroutines to have well-managed lifecycles. No uncontrolled background work that cannot be stopped. This change tries to distill some of the guidance around it into a style guide entry. In particular, - goroutines must end or be stoppable - APIs must block for goroutines to finish - `init()` should never spawn a goroutine
This PR fixes the link to the example golangci config file in .golangci.yml. Previously at https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml, now it's accessible at https://github.com/golangci/golangci-lint/blob/master/.golangci.reference.yml
markdownlint is a static analysis tool with a library of rules to enforce standards and consistency for Markdown files. [^1] This commit removes redundant spaces, unused references, indent mistakes, etc. from this document according to the report from `markdownlint`. Note that I disable `MD033` (no- inline-html) as it is necessary for side-by-side code samples. [^1]: https://github.com/DavidAnson/markdownlint Signed-off-by: pan93412 <pan93412@gmail.com>
* src: Copy contents from style.md
* Add CONTRIBUTING
* style.md: Generate from src/SUMAMRY.md
* {make, ci}: Set up machinery
* style.md: Add warning that the file is generated * ci: Fix setup-go action
Bumps [actions/setup-go](https://github.com/actions/setup-go) from 3 to 4. - [Release notes](https://github.com/actions/setup-go/releases) - [Commits](actions/setup-go@v3...v4)
Bumps [go.abhg.dev/stitchmd](https://github.com/abhinav/stitchmd) from 0.4.0 to 0.5.0. - [Release notes](https://github.com/abhinav/stitchmd/releases) - [Changelog](https://github.com/abhinav/stitchmd/blob/main/CHANGELOG.md) - [Commits](abhinav/stitchmd@v0.4.0...v0.5.0) --- updated-dependencies: - dependency-name: go.abhg.dev/stitchmd dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Adds new guidance on how handling errors once rather than double handling, e.g. log-and-return. Resolves #65
This replaces the manual compilation and running of stitchmd with the [stitchmd-action](https://github.com/abhinav/stitchmd-action). The action downloads a pre-built copy of stitchmd from GitHub, and runs it. The action offers multiple execution modes. Those relevant here are: - check: fail if the file is not up-to-date - write: update the file if it's not up-to-date The workflow added here uses both: - For a push to any branch, it will run in check mode. Read-only. It'll check that the file is up-to-date and that's it. - However, if a pull request is created with a branch, it will run in write mode -- automatically updating the PR if needed. This has some nice properties in terms of UX and safety: - We never push to a branch without permission. This alleviates safety concerns around automated pushes. - We make it easy to make edits on the GitHub UI, and still have them be picked up by the system without creating a local checkout - Setting up Go, building stitchmd from source, and then running it--all this takes some time. It's *a lot* faster to download and run the binary. The instructions taken to set up this dual mode can be found here: https://github.com/abhinav/stitchmd-action#automatically-update-for-prs-only Note that this nukes the tools/ directory, but keeps the `Makefile` so that if someone wants to run this locally, they still can.
#181 tried to fix support for PRs from forks by changing the event to pull_request_target. However, it did not update the check we do on github.event_name later to decide whether we're in check mode or write. This updates the job to fix the event name match.
Auto-commit to PRs only if the event is pull_request_target not pull_request, because we've changed the event we dispatch on.
The tables added in #174 are a bit wide and hard to fit on smaller screens. By changing the `\t` to ` `, and splitting a line, we can reduce this width.
Clarify that the example of using `run()` and `log.Fatal` isn't intended to be prescriptive. Provide samples of using `os.Exit` directly, using different exit codes, and clarify that there's flexibility here on how everything is set up. Refs #189
Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Adds a link to a Persian translation of the style guide maintained by @jamalkaksouri. Co-authored-by: jamalkaksouri <jamalkaksouri@users.noreply.github.com>
Clarify that the intent for string-to-byte conversions is to avoid repeated conversions. --------- Co-authored-by: alex-semenyuk <alex-semenyuk@users.noreply.github.com> Co-authored-by: Matt Way <mway@uber.com>
* chore: Update external Go links * Auto-update style.md --------- Co-authored-by: vorobeyme <vorobeyme@users.noreply.github.com>
* give guidance to reduce scope of constants * Auto-update style.md * Update var-scope.md Co-authored-by: Abhinav Gupta <mail@abhinavg.net> * Update var-scope.md Co-authored-by: Abhinav Gupta <mail@abhinavg.net> * Auto-update style.md --------- Co-authored-by: tyler-french <tyler-french@users.noreply.github.com> Co-authored-by: Abhinav Gupta <mail@abhinavg.net>
…anslations to enhance accessibility for Arabic speakers (#224)
Go 1.25 introduced https://pkg.go.dev/sync#WaitGroup, which simplified waiting for goroutines to finish. This PR updates the code example that uses WaitGroups.
Update WaitGroup example
Go 1.22, range loop variables are new per iteration automatically
Updated linting recommendations to replace golint with revive and added a note about revive being the successor to golint.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
20 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.