Security discrepancies between rake task and documentation

[pboling]

Describe the problem as clearly as you can

The documentation on Security for Rubygems is not congruent with the rake task for rake build:checksum, indeed the documentation doesn't seem to be aware of the checksum task at all.

Discrepancies

When I mention "Docs" I am referring to this article: https://guides.rubygems.org/security/

1. Docs say to put the checksum files in a checksum directory, but the build:checksum task puts them in a checksums (plural) directory.
2. Docs say to use a script to generate an SHA512 checksum, and do not mention the availability of the rake build:checksum task.
3. Docs and rake build:checksum task both refer to SHA512 checksums, but the checksum created for reference and display on rubygems.org is SHA256. Perhaps the rake task should generate both SHA256 and SHA512?
4. Checksum files creates by the rake task have an empty line at the end of the file, while when following the example script in the documentation an empty line does not result at the end of the checksum file. This may not matter much, but it is inconsistent, and, when running checksums, a change in the file, and thus a potential change in the git history, can be disconcerting, and waste brain cycles.

Did you try upgrading RubyGems?

Yes.

$ gem -v
3.3.22

Run gem env and paste the output below

$ gem env
RubyGems Environment:
  - RUBYGEMS VERSION: 3.3.22
  - RUBY VERSION: 3.1.2 (2022-04-12 patchlevel 20) [x86_64-darwin21]
  - INSTALLATION DIRECTORY: /Users/pboling/.asdf/installs/ruby/3.1.2/lib/ruby/gems/3.1.0
  - USER INSTALLATION DIRECTORY: /Users/pboling/.gem/ruby/3.1.0
  - RUBY EXECUTABLE: /Users/pboling/.asdf/installs/ruby/3.1.2/bin/ruby
  - GIT EXECUTABLE: /usr/local/bin/git
  - EXECUTABLE DIRECTORY: /Users/pboling/.asdf/installs/ruby/3.1.2/bin
  - SPEC CACHE DIRECTORY: /Users/pboling/.gem/specs
  - SYSTEM CONFIGURATION DIRECTORY: /Users/pboling/.asdf/installs/ruby/3.1.2/etc
  - RUBYGEMS PLATFORMS:
     - ruby
     - x86_64-darwin-21
  - GEM PATHS:
     - /Users/pboling/.asdf/installs/ruby/3.1.2/lib/ruby/gems/3.1.0
     - /Users/pboling/.gem/ruby/3.1.0
  - GEM CONFIGURATION:
     - :update_sources => true
     - :verbose => true
     - :backtrace => false
     - :bulk_threshold => 1000
     - :benchmark => false
     - :sources => ["http://rubygems.org"]
     - "gem" => "--no-document"
  - REMOTE SOURCES:
     - http://rubygems.org
  - SHELL PATH:
     - /Users/pboling/.asdf/installs/ruby/3.1.2/bin
     - /Users/pboling/.asdf/shims
     - /usr/local/Cellar/asdf/0.10.2/libexec/bin
     - /usr/local/opt/mysql@5.7/bin
     - /Users/pboling/.krew/bin
     - /usr/local/heroku/bin
     - /Users/pboling/.yarn/bin
     - /Users/pboling/.config/yarn/global/node_modules/.bin
     - /usr/local/sbin
     - /usr/local/opt/libxml2/bin
     - /Users/pboling/src/elasticsearch-6.4.3/bin
     - /Library/Java/JavaVirtualMachines/jdk-13.0.2.jdk/Contents/Home/bin
     - /usr/local/opt/icu4c/sbin
     - /usr/local/opt/icu4c/bin
     - /Users/pboling/.jx/bin/
     - /usr/local/opt/mysql@5.7/bin
     - /Applications/Postgres.app/Contents/Versions/latest/bin
     - /usr/local/git/bin
     - /usr/local/Homebrew/bin
     - /usr/local/Homebrew/sbin
     - /Users/pboling/bin
     - /Users/pboling/.bin
     - /Users/pboling/.local/bin
     - /usr/local/bin
     - /usr/bin
     - /bin
     - /usr/sbin
     - /sbin
     - /usr/local/MacGPG2/bin
     - /Library/Apple/usr/bin
     - /Users/pboling/.ec2/tools/bin

[deivid-rodriguez]

It sounds like we need to document the build:checksum task then, for points 1 and 2.

For 3 and 4, happy to take fixes too!