Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-customers-country-affiliation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Customers: a profile now has a country, shown as a small flag with its ISO code on the row and by name under Details. It is worked out from the location text with a bundled table, offline, and marked as derived; a country you set or clear by hand is never changed, and "Auto" hands it back. A likely organization is offered as a suggestion with its evidence (the GitHub company text, or the domain of an email you confirmed by hand); Accept sets it by hand, Dismiss is remembered. Notes keep their rules: owner and read-write only, in the export, deleted on Forget. No new requests are made and nothing is read from the hub.
6 changes: 4 additions & 2 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -2042,7 +2042,7 @@
"Customers"
],
"summary": "Edit a customer profile",
"description": "Applies one change, named by op: name, notes, profile (field real_name, organization or location, with value; state auto hands it back to GitHub), identity_add, identity_remove, tag (state on, off or auto), goal_add, goal_edit, goal_confirm, goal_reject, satisfaction_set, satisfaction_confirm, satisfaction_reject. Owner and read-write users may edit anyone. A read-only user may post only to /api/customers/me/edit, and only name, profile, identity, tag and goal changes; an identity they add is an unconfirmed claim that resolves nobody until someone with the full view confirms it. Audited as customer_edit with the person and the op, never the value.",
"description": "Applies one change, named by op: name, notes, profile (field real_name, organization, location or country, with value; a country is an ISO 3166 alpha-2 code or a country name; state auto hands it back to the automatic source, which derives a country from the location), affiliation_dismiss (value: a suggested organization the person refused), identity_add, identity_remove, tag (state on, off or auto), goal_add, goal_edit, goal_confirm, goal_reject, satisfaction_set, satisfaction_confirm, satisfaction_reject. Owner and read-write users may edit anyone. A read-only user may post only to /api/customers/me/edit, and only name, profile, affiliation_dismiss, identity, tag and goal changes; an identity they add is an unconfirmed claim that resolves nobody until someone with the full view confirms it. Audited as customer_edit with the person and the op, never the value.",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -2070,6 +2070,7 @@
"name",
"notes",
"profile",
"affiliation_dismiss",
"identity_add",
"identity_remove",
"tag",
Expand Down Expand Up @@ -2114,7 +2115,8 @@
"enum": [
"real_name",
"organization",
"location"
"location",
"country"
]
},
"goal_id": {
Expand Down
4 changes: 2 additions & 2 deletions src/docs/api-reference/customers.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ The rules are enforced twice: by the handlers and again by the store's service o
|---|---|---|---|---|
| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:178` |
| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:179` |
| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:180` |
| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `profile` (`field` of `real_name`, `organization` or `location`, `value`; `state` of `auto` hands the field back to GitHub), `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, profile, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:181` |
| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view, and `affiliation_suggestion` (`{value, rule, evidence}`, never stored) when a likely organization can be offered. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:180` |
| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `profile` (`field` of `real_name`, `organization`, `location` or `country`, `value`; a country is an ISO 3166 alpha-2 code or a country name; `state` of `auto` hands the field back to the automatic source, and a country is then derived again from the location), `affiliation_dismiss` (`value`, a suggested organization the person refused), `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, profile, affiliation_dismiss, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:181` |
| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:182` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. With the optional body `{into}` (an existing customer id, or `me`) it attaches the suggestion to that customer instead: the identity becomes one of theirs, pinned as a manual decision, no new person is created, the activity moves onto them on the next sweep, and `unmerge` undoes it with the id in the target's merge history. Audited as `customer_accept`, or `customer_attach` with the target's id and never a name. When `customers.mention_search.enabled` is on and the suggestion is a GitHub login, a budgeted background GitHub search adds `mentioned_in` and `commented_on` edges after the accept (see the design doc, step E) | `pkg/dashboard/api_customers.go:183` |
| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:184` |
Expand Down
22 changes: 21 additions & 1 deletion src/docs/design/customers.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ contributor is one of several sources of identity for a person.
| `goals` | See section 8. |
| `satisfaction` | See section 8. |
| `notes` | Free text, written by people only. |
| `profile` | Optional `real_name`, `organization` and `location`, each `{value, source, rule, at, by}`. `source` is `auto` (the person's own public GitHub profile name, company and location, fetched once on accept) or `manual` (a person typed it or cleared it; the fetch never changes it; `auto` hands it back). Nothing here comes from the hub. |
| `profile` | Optional `real_name`, `organization`, `location` and `country`, each `{value, source, rule, at, by}`. `source` is `auto` (the person's own public GitHub profile name, company and location, fetched once on accept; the country derived offline from the location, rule `location`) or `manual` (a person typed it or cleared it; neither the fetch nor the location changes it; `auto` hands it back). `country` is an ISO 3166 alpha-2 code. Also `dismissed_affiliations`, the suggested organizations a person refused (at most 20). Nothing here comes from the hub. |
| `merged_from` | Merge history, so a merge can be undone. |

**Identity** `{kind, value, source, confidence, manual, at, by}`. Kinds:
Expand Down Expand Up @@ -328,6 +328,26 @@ with the person and export includes them. The hub's own records of the same peop
(name, company, country, notes, inferred affiliation) are not read or copied: that
is the open question in section 15 and needs a consent decision first.

Country and likely affiliation add no request of their own. The country is derived
from the location text by a bundled table (country names and aliases, ISO codes, US
states and Canadian provinces, major cities; `pkg/customers/country_data.go`), offline
and deterministically. The last comma-separated piece decides, a bare two-letter code
after a comma reads as a US state first unless a city of another country precedes it
("Berlin, DE"), and "remote", "Earth" or an empty location give no country. It is a
guess about free text: a small city with no state or country, or a location that is
a joke, can be wrong or empty, so it is an automatic field a person overwrites or
clears, and a hand-set or hand-cleared country is never touched. A likely
affiliation is a view-time suggestion, never stored: the GitHub company text tidied
(legal suffix and "@" dropped, a bare handle capitalized), or, while the organization
is empty, the domain of an email identity a person confirmed by hand (never a
free-mail or code-host domain, and the address itself is not shown). It carries its
evidence ("from GitHub company field"), Accept writes it as a by-hand organization,
Dismiss remembers the refusal on the profile. Public GitHub organization membership
is deliberately not used: it is not fetched, and fetching it would be a new request.
Notes are free text up to 4000 bytes, written by the owner and read-write users, never
shown to a read-only user (not even on their own profile), part of the owner's export
and deleted with the person on Forget.

Step E, the budgeted GitHub search on accept, is built and opt-in.
`customers.mention_search.enabled` defaults to **off** (env
`HIVE_CUSTOMERS_MENTION_SEARCH_ENABLED`), because it asks GitHub about a person's
Expand Down
158 changes: 158 additions & 0 deletions src/pkg/customers/affiliation.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
package customers

import (
"strings"
"unicode"
)

// A likely affiliation is a suggestion about a person's organization, never a
// stored fact. SuggestAffiliation is pure and offline: it reads only what the
// profile already holds and makes no request. Accepting a suggestion writes it
// as a by-hand organization; dismissing it remembers the refusal.
//
// Rules, in order, for a profile whose organization a person has not set or
// cleared by hand:
//
// 1. company: the organization filled from the person's GitHub company text,
// tidied (legal suffix and "@" dropped, a bare lower-case handle given
// capitals). Offered only when the tidied form differs from what is shown.
// 2. email domain: the domain of an email identity a person confirmed by
// hand, when the organization is still empty and the domain is not a
// free-mail or code-host provider.
//
// Public GitHub organization membership is not used: it is not fetched today,
// and reading it would be a new network call.

// Affiliation suggestion evidence kinds.
const (
AffiliationFromCompany = "github_company"
AffiliationFromEmail = "email_domain"
)

// AffiliationSuggestion is one suggested organization with where it came from.
// Evidence is human-readable and never includes the email local part.
type AffiliationSuggestion struct {
Value string `json:"value"`
Rule string `json:"rule"`
Evidence string `json:"evidence"`
}

// shortOrgLen is the longest bare handle shown in capitals ("ibm" -> "IBM").
const shortOrgLen = 3

var legalSuffixes = map[string]bool{
"inc": true, "llc": true, "ltd": true, "corp": true, "corporation": true,
"gmbh": true, "co": true, "company": true, "ag": true, "plc": true,
"limited": true, "incorporated": true, "bv": true, "oy": true, "ab": true,
}

// freeMailDomains name no organization: a person's mailbox provider says
// nothing about where they work.
var freeMailDomains = map[string]bool{
"gmail.com": true, "googlemail.com": true, "outlook.com": true, "hotmail.com": true,
"live.com": true, "msn.com": true, "yahoo.com": true, "icloud.com": true, "me.com": true,
"proton.me": true, "protonmail.com": true, "aol.com": true, "gmx.com": true, "gmx.de": true,
"qq.com": true, "163.com": true, "126.com": true, "yandex.com": true, "mail.com": true,
"fastmail.com": true, "hey.com": true, "pm.me": true, "github.com": true,
"users.noreply.github.com": true, "noreply.github.com": true,
}

// secondLevelLabels are the generic labels that precede a country code in a
// registrable domain ("example.co.uk").
var secondLevelLabels = map[string]bool{"co": true, "com": true, "org": true, "net": true, "ac": true, "gov": true, "edu": true}

// TidyCompany makes a GitHub company string presentable: it drops "@", a
// trailing legal suffix and trailing punctuation, and gives a lower-case
// single word capitals (up to three letters) or a leading capital.
func TidyCompany(s string) string {
s = strings.TrimPrefix(strings.TrimSpace(s), "@")
words := strings.Fields(s)
for len(words) > 1 {
last := strings.ToLower(strings.Trim(words[len(words)-1], ".,"))
if !legalSuffixes[last] {
break
}
words = words[:len(words)-1]
}
out := strings.TrimRight(strings.Join(words, " "), ".,;")
if len(words) == 1 && out == strings.ToLower(out) {
return capitalizeOrg(out)
}
return out
}

func capitalizeOrg(s string) string {
if s == "" {
return ""
}
if len(s) <= shortOrgLen {
return strings.ToUpper(s)
}
r := []rune(s)
r[0] = unicode.ToUpper(r[0])
return string(r)
}

// orgFromDomain names the organization a mail domain implies, or "" for a
// free-mail or code-host domain.
func orgFromDomain(domain string) string {
domain = strings.ToLower(strings.Trim(strings.TrimSpace(domain), "."))
if domain == "" || freeMailDomains[domain] || !strings.Contains(domain, ".") {
return ""
}
labels := strings.Split(domain, ".")
n := len(labels)
idx := n - 2
if n >= 3 && len(labels[n-1]) == isoCodeLen && secondLevelLabels[labels[n-2]] {
idx = n - 3
}
if labels[idx] == "" {
return ""
}
return capitalizeOrg(labels[idx])
}

func affiliationDismissed(pr Profile, key string) bool {
for _, d := range pr.DismissedAffiliations {
if d == key {
return true
}
}
return false
}

// SuggestAffiliation returns the likely organization for p, or nil when a
// person has settled the field, nothing supports one, or the person refused it.
func SuggestAffiliation(p Person) *AffiliationSuggestion {
org := p.Profile.Organization
if org.Source == SourceManual {
return nil
}
ok := func(v string) bool {
return v != "" && len(v) <= MaxProfileFieldLen && !affiliationDismissed(p.Profile, strings.ToLower(v))
}
if org.Value != "" && org.Rule == ProfileSourceGitHub {
if v := TidyCompany(org.Value); v != org.Value && ok(v) {
return &AffiliationSuggestion{Value: v, Rule: AffiliationFromCompany,
Evidence: "from GitHub company field \"" + org.Value + "\""}
}
return nil
}
if org.Value != "" {
return nil
}
for _, id := range p.Identities {
if id.Kind != KindEmail || !id.Manual || id.Claimed {
continue
}
_, domain, found := strings.Cut(id.Value, "@")
if !found {
continue
}
if v := orgFromDomain(domain); ok(v) {
return &AffiliationSuggestion{Value: v, Rule: AffiliationFromEmail,
Evidence: "from email domain " + strings.ToLower(domain)}
}
}
return nil
}
Loading
Loading