x/build/internal/gophers: improve internal package design

[dmitshur]

Problem

Total mess, but a functional mess, and a starting point for the future.
— Commit 891b12dc

The gophers package is currently hard to use and hard to modify. It's not easy to read its documentation and start using it:

// (no documentation)
func GetPerson(id string) *Person

I've used and modified it multiple times, and each time, I had to read its internal code to figure out:

• what kind of value can "id" be?
• what is its exact format?
  • is leading '@' required for GH usernames? optional? unneeded?
• is it case sensitive or not?
• in what order/what type of information to add to the addPerson(...) lines?

Despite being an internal package, gophers is an important package providing value to 4 other packages, and potentially becoming used in more places. It's no longer just for computing stats, but also for tracking package owners and assigning reviews. Being internal means we can change it easily (even break the API if needed) if we come to agreement on an improved design.

Proposed Solution

I think it can be made easier to use by:

• documenting it (so its godoc is all you need to use it, no need to read code)

  For example:

  // GetPerson looks up a person by id and returns one if found, or nil otherwise.
  //
  // The id is case insensitive, and may be one of:
  // 	- full name ("Brad Fitzpatrick")
  // 	- GitHub username ("@bradfitz")
  // 	- Gerrit <account ID>@<instance ID> ("5065@62eb7196-b449-3ce5-99f1-c037f21e1705")
  // 	- email ("[email protected]")
  func GetPerson(id string) *Person

  @bradfitz If you prefer not to be used as an example, let me know, and we can use someone else (I'm happy to volunteer) or use a generic name. But I think a well known real user makes for a better example.

Made easier to modify by:

• making its internal addPerson logic more explicit rather than implicit

  For example, instead of what we have now:

  addPerson("Filippo Valsorda", "", "6195@62eb7196-b449-3ce5-99f1-c037f21e1705")
  addPerson("Filippo Valsorda", "[email protected]")
  addPerson("Filippo Valsorda", "[email protected]", "11715@62eb7196-b449-3ce5-99f1-c037f21e1705")
  addPerson("Filippo Valsorda", "[email protected]", "[email protected]", "@FiloSottile")
  
  // what kind of changes should be done to modify the end result Person struct?

  It could be something more explicit, along the lines of:

  add(Person{
  	Name:      "Filippo Valsorda",
  	GitHub:    "FiloSottile",
  	Gerrit:    "[email protected]",
  	GerritIDs: []int{6195, 11715}, // Gerrit account IDs.
  	GitEmails: []string{
  		"[email protected]",
  		"[email protected]",
  		"[email protected]",
  	},
  	gomote: "valsorda", // Gomote user.
  })

  The intention is to make it easy for people to manually add and modify their entries, with predictable results, while still being able to to use code generation (ala gopherstats -mode=find-gerrit-gophers) to add missing entries.

This is just a quick draft proposal, not necessarily the final API design. If the general direction is well received but there are concerns or improvement suggestions, I'm happy to flesh it out and incorporate feedback. I wouldn't send a CL until I have a solid design.

/cc @bradfitz @andybons

[andybons]

Given that this API is internal and you're only altering internals, I wouldn't spend a crazy amount of time worrying about implementation details. Do what you think is best for now and you can change it later on.

[gopherbot]

Change https://golang.org/cl/135456 mentions this issue: internal/gophers: restore valid Gerrit emails

[gopherbot]

Change https://golang.org/cl/195062 mentions this issue: internal/gophers: restore valid Gerrit emails (again)

[gopherbot]

Change https://golang.org/cl/195064 mentions this issue: internal/gophers: add missing documentation

[gopherbot]

Change https://go.dev/cl/386794 mentions this issue: internal/gophers: remove unused Gerrit group UUID