go-commons / commons

Commons is a community project focused on all aspects of reusable Go code.

commons

Commons is a community project focused on all aspects of reusable Go code.

This repository is for issues and general discussions. There will never be code in this repository. Commons packages will be repositories under the go-commons org and have import names under the gopher.rocks/commons vanity URL. e.g. gopher.rocks/commons/log

Versioning

Packages in this organization will be versioned individually. For example, if there is a strings package, it will be an individual Github repository, and maintain independent version tags.

Compatibility Guarantees

TBD, (strong)

Use of External Packages

The go-commons libraries will use only Go's standard library to avoid any external dependencies. This pragmatic choice allows us to better prevent breakage in the libraries we create.

Code Standards

Tests

Go Standards

Code Review Process

Governance

See the wiki

commons's Issues

strings package

I think a relatively quick win would be a package with string utilities. Does anyone have some common string utils that would be good candidates?

License agreement

We need to choose a license for the packages in these repositories.

I've always preferred MIT, but am open to a BSD style license or similar. Nothing like GPL vX that is too prohibitive. If you have preferences or opinions please weigh in here.

External Package Usage

My initial thought was that we would prohibit bringing in dependencies to external packages. It's probably obvious why we'd prefer that as library authors.

Opened this issue to discuss the pros & cons of allowing external packages, and ways to mitigate maintenance risks if we choose to allow them.

CLA

Do we need to require a CLA for contributions? I don't believe we have the need, but I'm not the most knowledgable person on IP laws. Discussion here, please.

Governance Model

I would find it helpful to know what the governance model of the Commons is supposed to be. Specifically, how are decisions made? The Go project has it a bit easier getting away without a clear process, because they started with a clearly defined set of defined "Go team members" that could come to a consensus. In that way, they are something like a "consensus-based meritocracy". Given that the commons start from zero, there isn't much merit to base decision-making on. Brian mentioned a set of "veteran Gophers" that decided to start this project; if the current mode is that they come to a consensus, then it would be helpful to know that set.

For me, having a clear view of how a decision is made, what arguments are looked for and what criteria are valued, is pretty important when deciding how much and what to contribute to a discussion. Not to mention that there is a practical question of "when is a discussion 'over'", i.e. who decides to close it out?

communications for maintainers

We probably need a back-channel communication between organization maintainers. I created #go-commons on the gopherslack. Email might be good? A private google group? Or everything in the open in GH issues (very open and community friendly!)

Code of conduct

Even with the best of communities, communications can become strained. I would love to see a Code of Conduct in place here from the get-go to keep things as welcome & inclusive as possible.

I know that Github has some boiler-plate stuff. Is anything more that that required to start?

Missing Set implementation (or other data structures)

Golang is missing a Set implementation (and other data structures); the reason seems that it's easy to write it with maps, but I find it cumbersome and annoying.
Maybe having a simple Set implementation could be useful, or at least more expressive?

It will be nice to use something like:

var mySet = set.New("val1", "val2")
if mySet.Contains(value) {
    // do things
}

instead of

var mySet = map[string]bool{}{
    "val1": true,
    "val2": true,
}

if _, has := mySet[value]; has {
    // do things
}

This could be also powered with other useful methods like intersections, unions and so on.
A nice and complete lib here: https://github.com/fatih/set (nevere used it though).

Simple example here: https://play.golang.org/p/vC5cnTLL2Z

package main

import (
	"fmt"
)

type Set map[interface{}]struct{}

func New(values ...interface{}) Set {
	s := make(map[interface{}]struct{})
	for _, v := range values {
		s[v] = struct{}{}
	}
	return s
}

func (s Set) Contains(v interface{}) bool {
	_, has := s[v]
	return has
}

func (s Set) Remove(v interface{}) {
	delete(s, v)
}

func main() {
	s := New("a", "b", 123)
	fmt.Println(`Has "a"?`, s.Contains("a"))
	fmt.Println(`Has "c"?`, s.Contains("c"))
	s.Remove("a")
	fmt.Println(`Has "a"?`, s.Contains("a"))
	fmt.Println(`Has '123'?`, s.Contains(123))
	fmt.Println(`Has "123"?`, s.Contains("123"))
}

This could be extended to other data structures, maybe in a common datastructure package.

Struct / Payload validation and error formatting

I believe payload validation is a pretty common task when writing HTTP/gRPC servers (and others). While existing libraries allow us to validate pretty much anything, by experience it's very complicated to customize them so they can return errors that can be formatted the way we want.
(Not sure if you are expecting this kind of issues so i apologize in advance if it's not relevant.)

Proposed Design Principles

Over in go-commons/event#1 (comment) I agreed to draft a design philosophy. Here is my first draft.

API Design Principles

When designing anything we should have some core principles in mind to guide
our decisions. Designing a good package API, especially one that aims for
general use by a wide audience, takes careful thought, attention to detail,
and wise consideration of the alternatives.

Here are three API design principles that should guide our work in go-commons.
These principles are excerpted from "API: Design Matters" by Michi Henning
that appeared in ACM Queue (Volume 5, issue 4). A good API is:

• Minimal, without imposing undue inconvenience on the caller.
• Designed from the perspective of the caller.
• Policy-free when general-purpose and policy-rich when special-purpose.

The article does a good job describing these principles and explaining why
they are important. It also includes some additional principles, but I feel
that the three I've chosen are the most salient and motivating. It is not easy
to design an API that lives up to these principles, but that should always be
our goal.

Standard logger interface.

I'm sitting in the upper balcony and wondered if here was the place to get the new standard logger interface nailed down.

Keeping interfaces small is something I can stand behind, but logging seems like a nebulous topic.

I'm going to flesh this out later, first thought is that logging should concern itself with the Printf family of functions, and levels should be implemented by returning a new logger with an internal tags representing the level.