From 68f9c8c0d08307beb33611a9f58140620f644f1c Mon Sep 17 00:00:00 2001 From: Akshay Shah Date: Sun, 29 May 2016 20:50:32 -0700 Subject: [PATCH] Add docs and linters before release (#6) * Add a lint target to Makefile * Add a README * Add a simple example * Add a PR template * Show off usable zero values --- .github/PULL_REQUEST_TEMPLATE.md | 8 ++++++ .gitignore | 2 +- LICENSE => LICENSE.txt | 0 Makefile | 34 ++++++++++++++++++++++++- README.md | 34 +++++++++++++++++++++++++ example_test.go | 43 ++++++++++++++++++++++++++++++++ 6 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md rename LICENSE => LICENSE.txt (100%) create mode 100644 README.md create mode 100644 example_test.go diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8ef55f8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,8 @@ +Before opening your pull request, please make sure that you've: + +- [ ] [signed Uber's Contributor License Agreement](https://docs.google.com/a/uber.com/forms/d/1pAwS_-dA1KhPlfxzYLBqK6rsSWwRwH95OCCZrcsY5rk/viewform); +- [ ] added tests to cover your changes; +- [ ] run the test suite locally (`make test`); and finally, +- [ ] run the linters locally (`make lint`). + +Thanks for your contribution! diff --git a/.gitignore b/.gitignore index a2b5e5d..0a4504f 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,7 @@ /vendor /cover cover.out - +lint.log # Binaries *.test diff --git a/LICENSE b/LICENSE.txt similarity index 100% rename from LICENSE rename to LICENSE.txt diff --git a/Makefile b/Makefile index f3e1b3e..9f757ff 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,17 @@ PACKAGES := $(shell glide novendor) +# Many Go tools take file globs or directories as arguments instead of packages. +PACKAGE_FILES ?= *.go + + +# The linting tools evolve with each Go version, so run them only on the latest +# stable release. +GO_VERSION := $(shell go version | cut -d " " -f 3) +GO_MINOR_VERSION := $(word 2,$(subst ., ,$(GO_VERSION))) +LINTABLE_MINOR_VERSIONS := 6 +ifneq ($(filter $(LINTABLE_MINOR_VERSIONS),$(GO_MINOR_VERSION)),) +SHOULD_LINT := true +endif + export GO15VENDOREXPERIMENT=1 @@ -24,9 +37,28 @@ install_ci: install go get github.com/wadey/gocovmerge go get github.com/mattn/goveralls go get golang.org/x/tools/cmd/cover +ifdef SHOULD_LINT + go get github.com/golang/lint/golint +endif + +.PHONY: lint +lint: +ifdef SHOULD_LINT + @rm -rf lint.log + @echo "Checking formatting..." + @gofmt -d -s $(PACKAGE_FILES) 2>&1 | tee lint.log + @echo "Checking vet..." + @$(foreach dir,$(PACKAGE_FILES),go tool vet $(dir) 2>&1 | tee -a lint.log;) + @echo "Checking lint..." + @$(foreach dir,$(PKGS),golint $(dir) 2>&1 | tee -a lint.log;) + @echo "Checking for unresolved FIXMEs..." + @git grep -i fixme | grep -v -e vendor -e Makefile | tee -a lint.log + @[ ! -s lint.log ] +else + @echo "Skipping linters on" $(GO_VERSION) +endif .PHONY: test_ci test_ci: install_ci build ./scripts/cover.sh $(shell go list $(PACKAGES)) - diff --git a/README.md b/README.md new file mode 100644 index 0000000..e80f718 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# atomic [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] + +Simple numeric wrappers to enforce atomic access. + +## Installation +`go get -u github.com/uber-go/atomic` + +## Usage +The standard library's `sync/atomic` is powerful, but it's easy to forget which +variables must be accessed atomically. `uber-go/atomic` preserves all the +functionality of the standard library, but wraps the primitive numeric types to +provide a safer, more convenient API. + +```go +var atom atomic.Uint32 +atom.Store(42) +atom.Sub(2) +atom.CAS(40, 11) +``` + +See the [documentation][doc] for a complete API specification. + +## Development Status +Stable. + +
+Released under the [MIT License](LICENSE.txt). + +[doc-img]: https://godoc.org/github.com/uber-go/atomic?status.svg +[doc]: https://godoc.org/github.com/uber-go/atomic +[ci-img]: https://travis-ci.org/uber-go/atomic.svg?branch=master +[ci]: https://travis-ci.org/uber-go/atomic +[cov-img]: https://coveralls.io/repos/github/uber-go/atomic/badge.svg?branch=master +[cov]: https://coveralls.io/github/uber-go/atomic?branch=master diff --git a/example_test.go b/example_test.go new file mode 100644 index 0000000..9b296d3 --- /dev/null +++ b/example_test.go @@ -0,0 +1,43 @@ +// Copyright (c) 2016 Uber Technologies, Inc. +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +// THE SOFTWARE. + +package atomic_test + +import ( + "fmt" + + "github.com/uber-go/atomic" +) + +func Example() { + // Uint32 is a thin wrapper around the primitive uint32 type. + var atom atomic.Uint32 + + // The wrapper ensures that all operations are atomic. + atom.Store(42) + fmt.Println(atom.Inc()) + fmt.Println(atom.CAS(43, 0)) + fmt.Println(atom.Load()) + + // Output: + // 43 + // true + // 0 +}