From 5cdaf26a8e2693679ee45d84fb29cd26cbf034af Mon Sep 17 00:00:00 2001 From: Jun Aruga Date: Thu, 16 Nov 2023 19:17:17 +0100 Subject: [PATCH] Use Markdown reference-style links in documents. [ci skip] Use Markdown reference-style links due to a better readability. See for details. --- CONTRIBUTING.md | 55 ++++++++++++++++++++++++------------------------- README.md | 9 +++++--- 2 files changed, 33 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index afc6d932b..fa68de651 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Bugs and feature requests are tracked on [GitHub]. If you think you found a bug, file a ticket on GitHub. Please DO NOT report security issues here, there is a separate procedure which is described on -["Security at ruby-lang.org"](https://www.ruby-lang.org/en/security/). +["Security at ruby-lang.org"][Ruby Security]. When reporting a bug, please make sure you include: @@ -22,26 +22,25 @@ When reporting a bug, please make sure you include: There are a number of unresolved issues and feature requests for openssl that need review. Before submitting a new ticket, it is recommended to check -[known issues]. +[known issues][Issues]. ## Submitting patches Patches are also very welcome! -Please submit a [pull request] with your changes. +Please submit a [pull request][Compare changes] with your changes. Make sure that your branch does: * Have good commit messages -* Follow Ruby's coding style ([DeveloperHowTo]) +* Follow Ruby's coding style ([Developer-How-To][Ruby Developer-How-To]) * Pass the test suite successfully (see "Testing") ## Testing We have a test suite! -Test cases are located under the -[`test/openssl`](https://github.com/ruby/openssl/tree/master/test/openssl) +Test cases are located under the [`test/openssl`][GitHub test/openssl] directory. You can run it with the following three commands: @@ -58,9 +57,9 @@ Ruby OpenSSL supports various versions of the OpenSSL library. The test suite needs to pass on all supported combinations. If you want to test, debug, report an issue, or contribute to the Ruby OpenSSL -or [the OpenSSL project](https://www.openssl.org/) in the non-FIPS or -the [FIPS](https://github.com/openssl/openssl/blob/master/README-FIPS.md) case, -compiling OpenSSL from the source by yourself is a good practice. +or [the OpenSSL project][OpenSSL] in the non-FIPS or the +[FIPS][OpenSSL README-FIPS] case, compiling OpenSSL from the source by yourself +is a good practice. The following steps are tested in Linux and GCC environment. You can adjust the commands in the steps for a different environment. @@ -104,20 +103,16 @@ $ OPENSSL_DIR=$HOME/.openssl/openssl-fips-debug-0bf18140f4 ``` The following configuration options are useful in this case. -You can check -[OpenSSL installation document](https://github.com/openssl/openssl/blob/master/INSTALL.md) -for details. +You can check [OpenSSL installation document][OpenSSL INSTALL] for details. * `enable-fips`: Add an option to run with the OpenSSL FIPS module. * `enable-trace`: Add an option to enabling tracing log. You can trace logs by - implementing a code. See the man page - [OSSL_TRACE(3)](https://www.openssl.org/docs/man3.0/man3/OSSL_TRACE.html) for + implementing a code. See the man page [OSSL_TRACE(3)][OpenSSL OSSL_TRACE] for details. * compiler flags * `-Wl,-rpath,$(LIBRPATH)`: Set the runtime shared library path to run the `openssl` command without the `LD_LIBRARY_PATH`. You can check - [this document](https://github.com/openssl/openssl/blob/master/NOTES-UNIX.md) - for details. + [this document][OpenSSL NOTES-UNIX] for details. * `-O0 -g3 -ggdb3 -gdwarf-5`: You can set debugging compiler flags. ``` @@ -173,8 +168,7 @@ To use OpenSSL 3.0 or later versions in a FIPS-approved manner, you must load th property query is used when fetching cryptographic algorithm implementations. This must be done at the startup of a process to avoid implicitly loading the `default` provider which has the non-FIPS cryptographic algorithm -implementations. See also the man page -[fips_module(7)](https://www.openssl.org/docs/manmaster/man7/fips_module.html). +implementations. See also the man page [fips_module(7)][OpenSSL fips_module]. You can set this in your OpenSSL configuration file by either appropriately modifying the default OpenSSL configuration file located at @@ -227,10 +221,8 @@ $ OPENSSL_CONF=$OPENSSL_DIR/ssl/openssl_fips.cnf \ bundle exec rake test ``` -The GitHub Actions workflow file -[`test.yml`](https://github.com/ruby/openssl/tree/master/.github/workflows/test.yml) -contains useful information for building OpenSSL/LibreSSL and testing against -them. +The GitHub Actions workflow file [`test.yml`][GitHub test.yml] contains useful +information for building OpenSSL/LibreSSL and testing against them. ## Relation with Ruby source tree @@ -255,7 +247,7 @@ security issue handling procedure for Ruby core. You can either use [HackerOne] or send an email to security@ruby-lang.org. -Please see [Security] page on ruby-lang.org website for details. +Please see [Security][Ruby Security] page on ruby-lang.org website for details. Reported problems will be published after a fix is released. @@ -264,9 +256,16 @@ _Thanks for your contributions!_ _\- The Ruby OpenSSL team_ [GitHub]: https://github.com/ruby/openssl -[known issues]: https://github.com/ruby/openssl/issues -[DeveloperHowTo]: https://bugs.ruby-lang.org/projects/ruby/wiki/DeveloperHowto +[Issues]: https://github.com/ruby/openssl/issues +[Compare changes]: https://github.com/ruby/openssl/compare +[GitHub test/openssl]: https://github.com/ruby/openssl/tree/master/test/openssl +[GitHub test.yml]: https://github.com/ruby/openssl/tree/master/.github/workflows/test.yml +[Ruby Developer-How-To]: https://github.com/ruby/ruby/wiki/Developer-How-To +[Ruby Security]: https://www.ruby-lang.org/en/security/ [HackerOne]: https://hackerone.com/ruby -[Security]: https://www.ruby-lang.org/en/security/ -[pull request]: https://github.com/ruby/openssl/compare -[History.md]: https://github.com/ruby/openssl/tree/master/History.md +[OpenSSL]: https://www.openssl.org/ +[OpenSSL INSTALL]: https://github.com/openssl/openssl/blob/master/INSTALL.md +[OpenSSL README-FIPS]: https://github.com/openssl/openssl/blob/master/README-FIPS.md +[OpenSSL NOTES-UNIX]: https://github.com/openssl/openssl/blob/master/NOTES-UNIX.md +[OpenSSL OSSL_TRACE]: https://www.openssl.org/docs/manmaster/man3/OSSL_TRACE.html +[OpenSSL fips_module]: https://www.openssl.org/docs/manmaster/man7/fips_module.html diff --git a/README.md b/README.md index b57758b2a..0b31f7d17 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,7 @@ included as a default gem in [supported Ruby branches][Ruby Maintenance Branches > **Note** > The openssl gem is included with Ruby by default, but you may wish to upgrade -> it to a newer version available at -> [rubygems.org](https://rubygems.org/gems/openssl). +> it to a newer version available at [rubygems.org][RubyGems.org openssl]. To upgrade it, you can use RubyGems: @@ -59,6 +58,8 @@ gem 'openssl', git: 'https://github.com/ruby/openssl' After running `bundle install`, you should have the gem installed in your bundle. +[RubyGems.org openssl]: https://rubygems.org/gems/openssl + ## Usage Once installed, you can require "openssl" in your application. @@ -80,4 +81,6 @@ Please read our [CONTRIBUTING.md] for instructions. ## Security Security issues should be reported to ruby-core by following the process -described on ["Security at ruby-lang.org"](https://www.ruby-lang.org/en/security/). +described on ["Security at ruby-lang.org"][Security]. + +[Security]: https://www.ruby-lang.org/en/security/