Contributors

assigned and comment author are free text, and they always will be. There is no authentication in Kanbn and there is never going to be any, so it cannot and should not try to prove that a given string corresponds to a given human — anyone who can edit .kanbn/tasks/*.md can write any name they like into any field.

What Kanbn can do is make the common case — "that's me" — a single keystroke instead of a retyped name, and make the set of names a workspace uses discoverable rather than folkloric. That is what contributors is for.

Contributors are a convenience list, not an access control list. Nothing is validated against them, nothing is rejected, and nothing in an existing workspace changes when you add them.

Declaring contributors#

contributors is a workspace-scoped option: it goes in kanbn.yml / kanbn.json, or in the main board's front matter when there is no configuration file, and every board in the workspace inherits it. A secondary board that declares its own is reported by kanbn validate and ignored — a name written into a shared task file has to mean the same thing on every board that references that file.

The shorthand is a bare name, which is all most workspaces ever need:

contributors:
  - gordon
  - dave
  - sam

The long form is for a contributor who needs more than a name. Both forms can appear in the same list:

contributors:
  - name: gordon
    displayName: Gordon Larrigan
    email: gordonlarrigan@example.com
    aliases:
      - Gordon Larrigan
      - gordonl
    colour: '#7c5cff'
  - dave

aliases is the field that does the actual work. Without it, contributors is a list of strings a UI can put in a dropdown; with it, Kanbn can tell that the person at this machine is gordon even though git says Gordon Larrigan.

The current user#

Kanbn resolves a single answer to "who is the current user?", used by the CLI, the library and the VSCode extension. In order, first match wins:

1. the KANBN_USER environment variable, used exactly as given
2. git config user.email matched against a contributor's email → that contributor's name
3. git config user.name matched against a contributor's name, displayName or aliases, ignoring case → that contributor's name
4. git config user.name as-is
5. nobody

Two things follow from that order:

• It degrades to what Kanbn has always done. With no contributors declared, steps 2 and 3 can't match and step 4 returns exactly the git username Kanbn used before this feature existed. A workspace that ignores contributors sees no change at all.
• It canonicalises. With contributors declared, a machine whose git username is Gordon Larrigan writes gordon into the task file, because that is what the workspace has agreed to call him. That is the typo mitigation, and it happens without anyone typing anything.

KANBN_USER is used verbatim rather than canonicalised: it is the explicit override, for a machine whose git identity is wrong or missing, and an explicit value should be written exactly as given.

Ask Kanbn who it thinks you are with kanbn contributors.

There is deliberately no me key in the config file. A me committed into a shared board file would tell every collaborator that they are you. KANBN_USER plus git resolution covers the real cases.

What uses it#

@me is only ever interpreted in a filter argument, never when setting a value and never inside a task file. If the current user can't be resolved, @me is an error rather than a filter that quietly matches everything.

Adopting contributors in an existing workspace#

kanbn contributors --usage shows how each contributor is actually used, and — the useful part — every name used in a task that isn't a known contributor:

$ kanbn contributors --usage
2 contributors:

gordon (you)
  14 tasks, assigned 12, 4 comments
  written as "Gordon Larrigan" in 2 tasks

dave
  6 tasks, assigned 6, 1 comment

1 name is used in tasks but isn't a known contributor:

Gordon
  12 tasks, assigned 12, 0 comments
  task-1, task-4, task-9, ...

That is the list of aliases to add. It is read-only: nothing is rewritten, because renaming Gordon to gordon across every task file is a bulk mutation that deserves its own command and its own dry run.

kanbn validate reports the same thing more briefly, as a warning rather than an error — the tasks it names are working exactly as they always have. Nothing is reported at all when a workspace declares no contributors.

Deliberate omissions#

• Validation. assigned is never restricted to the contributor list. "If contributors is set, only allow those values" turns an optional convenience into something that breaks a workspace whenever someone adds a task on a machine with a stale config, or renames themselves, or receives a task file from outside.
• Multiple assignees. assigned is a single string in the schema, the filters, the board template and three reporting commands. One assignee per task.
• Importing from package.json, .mailmap or CODEOWNERS. npm contributors are publishers, .mailmap is git plumbing, and CODEOWNERS is a permissions file — three different sets of semantics, none of them this one.
• Anything resembling accounts. No permissions, no ownership, no invites. If contributors ever grows those, it has become an auth system by accident.