📖 Use scorecard (singular) consistently

[lehors]

Signed-off-by: Arnaud J Le Hors lehors@us.ibm.com

What kind of change does this PR introduce?

Improvement

What is the current behavior?

Both "scorecards" and "scorecard" are used.

What is the new behavior (if this is a feature change)?**

"scorecard" is used consistently, with a couple of exceptions that would require a breaking change:
https://api.securityscorecards.dev/...
https://slack.openssf.org/#security_scorecards

Which issue(s) this PR fixes

Fixes #2427

Special notes for your reviewer

This change is not strictly limited to the documentation because it also changes a couple of lines of code to use "RunScorecard" instead "RunScorecards" for consistency.

Does this PR introduce a user-facing change?

The singular form "scorecard" is now used consistently.

The singular form "scorecard" is now used consistently. 

[github-actions]

Integration tests success for
[ca7851b]
(https://github.com/ossf/scorecard/actions/runs/3395896326)

[olivekl]

Thanks for bringing this up! I'd like to open it for discussion so we can codify whether it's Scorecards or Scorecard going forward. My understanding is that:

• the repo was named scorecard
• with time, it seems like folks started using Scorecards (plural) to refer to the tool, and scorecard (singular) to refer to a single project's results
• the folks who built securityscorecards.dev wanted "Security Scorecards" to be used as a phrase when referring to the tool, never just Scorecards or Scorecard
• but this last point hasn't caught on, and it's rare to hear anyone say "Security Scorecards" outside the site.

I slightly prefer Scorecards but realize that consistency with the repo name and commands using scorecard (singular) is probably most important.

[naveensrinivasan]

Thanks for bringing this up! I'd like to open it for discussion so we can codify whether it's Scorecards or Scorecard going forward. My understanding is that:

• the repo was named scorecard
• with time, it seems like folks started using Scorecards (plural) to refer to the tool, and scorecard (singular) to refer to a single project's results
• the folks who built securityscorecards.dev wanted "Security Scorecards" to be used as a phrase when referring to the tool, never just Scorecards or Scorecard
• but this last point hasn't caught on, and it's rare to hear anyone say "Security Scorecards" outside the site.

I slightly prefer Scorecards but realize that consistency with the repo name and commands using scorecard (singular) is probably most important.

+1

[justaugustus]

• the folks who built securityscorecards.dev wanted "Security Scorecards" to be used as a phrase when referring to the tool, never just Scorecards or Scorecard

• but this last point hasn't caught on, and it's rare to hear anyone say "Security Scorecards" outside the site.

Important to note, especially because I haven't seen it mentioned elsewhere, is that there is a company called SecurityScorecard.

scorecards seems safer to standardize on, but regardless of the name we land on, I wholeheartedly agree with making this consistent across both the copy and the tooling.

[olivekl]

Important to note, especially because I haven't seen it mentioned elsewhere, is that there is a company called SecurityScorecard.

Yes, good point. I've seen it cause confusion at least once among maintainers. Someone recommended Scorecards Action and the repo badge to a project, and the maintainers responded that they weren't interested in displaying a badge linked to a security consulting company.

[lehors]

For what it's worth, I think it would make sense to use "Scorecards" for the project name and "scorecard" for the tool, conveying the idea that the project is about the production of scorecards (for many projects) and that the tool just produces one scorecard. This would require a much more careful update of the docs to comb through all the instances and figure out which one it refers to though.

When it comes to the collision with the security company one way to address it is to prefix the name with OpenSSF. This is how many open source projects avoid having to register trademarks for all of their projects. They only need to trademark the prefix. In this case you'd have to use "OpenSSF Security Scorecard". Note that you don't need to use this long form every single time. It typically suffices to do so on the first instance, like in the title of the README.md

[lehors]

Hey, how about dropping Security altogether and simply calling it "OpenSSF Scorecard", and "Scorecard" for short? That would solve the possible conflict with the company SecurityScorecard for sure and I don't think there would be any possible confusion as to what it is about.

[codecov]

Codecov Report

Merging #2428 (3f2a7cb) into main (c61f6bc) will not change coverage.
The diff coverage is 0.00%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2428   +/-   ##
=======================================
  Coverage   40.70%   40.70%           
=======================================
  Files         115      115           
  Lines        9593     9593           
=======================================
  Hits         3905     3905           
  Misses       5409     5409           
  Partials      279      279           

[github-actions]

Integration tests success for
[1417961]
(https://github.com/ossf/scorecard/actions/runs/3471168494)

[olivekl]

Hey, how about dropping Security altogether and simply calling it "OpenSSF Scorecard", and "Scorecard" for short? That would solve the possible conflict with the company SecurityScorecard for sure and I don't think there would be any possible confusion as to what it is about.

There's the domain name (securityscorecards.dev) to consider, but I'm fine with dropping "Security" and sticking with "OpenSSF Scorecard(s)". That still leaves the singular-vs-plural question. @azeemshaikh38 @laurentsimon @brianrussell2 can you weigh in?

[lehors]

Thanks. Let me add that, given that the repo and the binary are called "scorecard" and (I assume) nobody wants to disrupt everything by changing either of those we cannot get rid of the singular form. So, the options are:

1. consolidate around the singular form
2. use plural when referring to the project and singular for the binary/program (practically speaking, I had a look at that, and that means we'll mostly have singular everywhere and only use the plural form in a few instances such as the title of the README or when referring to the "Scorecards project".)

I don't mind updating the PR to do the latter if that's what the maintainers prefer but I honestly don't think it's worth the trouble.

[github-actions]

Integration tests success for
[5e67ab4]
(https://github.com/ossf/scorecard/actions/runs/3496060051)

[azeemshaikh38]

Sorry for the delayed response here. Thanks @lehors for starting this. My vote would be for the consistent usage of the singular term - Scorecard here. For the domain, FWIW, we (OpenSSF/Linux Foundation) own scorecard.dev and we can migrate to that one if its the only blocker to moving to the singular usage. Although I won't promise the domain move will happen soon. Any work related to domain name updates has been painstakingly slow (I cannot emphasis slow enough). But if we decide to use singular consistently I'll get the ball rolling on the domain update too and we can also ensure any new usage of Scorecard adheres to this principle.

@justaugustus @laurentsimon @naveensrinivasan @olivekl @spencerschrock please vote and provide your inputs. Let's aim to get a majority vote on this soon and try to get this merged in. Can also use the bi-weekly call if needed too.

[spencerschrock]

As someone who came late (2022) to the project, I've always heard and referred to it as Scorecard, so my vote is consolidating on the singular. I think scorecard.dev works good as a domain too.

That said, scorecard is a common term, so I'm also in favor of clarifying with OpenSSF Scorecard where relevant.

[olivekl]

@justaugustus @laurentsimon @naveensrinivasan @olivekl @spencerschrock please vote and provide your inputs. Let's aim to get a majority vote on this soon and try to get this merged in. Can also use the bi-weekly call if needed too.

I feel better about consolidating around Scorecard knowing that we can move to scorecard.dev, even if it takes some time to get there. It's a better domain, especially given the Security Scorecards confusion mentioned earlier. I vote to use Scorecard going forward and to try to get that migration underway when possible. We could also add a question to the FAQ to clarify (since there are so many blog posts out there calling it Scorecards that will live on even after we update documentation).

[github-actions]

Integration tests success for
[a727cf3]
(https://github.com/ossf/scorecard/actions/runs/3573455176)

[lehors]

I changed the name to OpenSSF Scorecard in the README and CONTRIBUTING files as well as added a FAQ entry.
However, I noticed that the copyright throughout the repo reads: "Copyright 2022 Security Scorecard Authors". It would be logical to update it to "Copyright 2022 OpenSSF Scorecard Authors" but we might want to consult the LF legal team on how to manage that.
It might be best to handle the change from "Security Scorecard" to "OpenSSF Scorecard" in a separate PR. (btw the copyright is using the singular form!)
@mkdolan do you have any advice?
Thanks.

[mkdolan]

"Copyright 2022 OpenSSF Scorecard Authors" looks ok to me.

[azeemshaikh38]

Thanks @lehors and @mkdolan!

@spencerschrock @laurentsimon @justaugustus please do chime in on this. We have 2 votes for OpenSSF Scorecard (singular) so far. Will wait for one more +1 before getting this merged.

[spencerschrock]

@spencerschrock @laurentsimon @justaugustus please do chime in on this. We have 2 votes for OpenSSF Scorecard (singular) so far. Will wait for one more +1 before getting this merged.

Already replied above in favor. Not sure if you were counting me as one of the two votes

[naveensrinivasan]

👍

[justaugustus]

@lehors -- Thanks for the work on this!

Adding an approval via GitHub to merge this in.

[justaugustus]

@olivekl -- you'll need to approve as well as docs CODEOWNER

[github-actions]

Integration tests success for
[3f2a7cb]
(https://github.com/ossf/scorecard/actions/runs/3586694362)

[gal-legit]

FYI this change in pkg/scorecard.go was a breaking change, should've gone into a new major Semver - or at least have a deprecated alias.