Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc(layout): Encourage use of username with set_user #22

Merged
merged 3 commits into from
Jan 24, 2022

Conversation

ketiltrout
Copy link
Member

@ketiltrout ketiltrout commented Dec 10, 2021

The previous layout docuemntation implied you needed to pass your "real name" (whatever that is) when calling set_user.
This is problematic for a few reasons:

  • it confuses the notion of someone's actual name and the value of the CHIMEwiki user_real_name field (which is what's being matched here)
  • the user_real_name field is typically populated by sysadmins when creating a wiki account. It's available and can be changed by users in the wiki profile page, but most wiki users don't change it nor do they even know what the value has been set to.
  • There's absolutely no validation performed on the column. I've seen misspelled names, blank names, email addresses in this column.
  • There's no requirement that the values of user_real_name be unique.

This changes the docs to encourage using CHIMEwiki usernames when calling set_user. Usernames are much better to use because:

  • they're guaranteed to be unique
  • they're unambiguous in form, meaning simple string matching is a reasonable thing to do.
  • they're well known to users, since users use them to log into the wiki

Note: this doesn't change any functionality: users are still able to pass the value of the user_real_name field associated
with their account to this function.

(Bonus reading: Personal names are never a good thing to key a database on for multiple reasons)

The previous layout docuemntation implied you needed to pass
your "real name" (whatever that is) when calling `set_user`.
This is problematic for a few reasons:
- it confuses the notion of someone's actual name and the
  value of the CHIMEwiki user_real_name field (which is what's
  being matched here)
- the user_real_name field is typically populated by sysadmins
  when creating a wiki account.  It's available and can be
  changed by users in the wiki profile page, but most wiki users
  don't change it nor do they even know what the value has
  been set to.
- There's absolutely no validation performed on the column.  I've
  seen misspelled names, blank names, email addresses in this
  column.
- There's no requirement that the values of `user_real_name` be
  unique.

This changes the docs to encourage using CHIMEwiki usernames when
calling `set_user`.  Usernames are much better to use because:
- they're unambiguous in form, mean simple string matching is a
  reasonable thing to do.
- they're well known to users, since users use them to log into the
  wiki

Note: this doesn't change any functionality: users are still
able to pass the value of the user_real_name field associated
with their account to this function.
@anjakefala
Copy link
Contributor

Thanks for the documentation on the change!

@ketiltrout ketiltrout merged commit 2135041 into master Jan 24, 2022
@ketiltrout ketiltrout deleted the set_user_doc branch January 24, 2022 20:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants