Adopt ExDoc & Move Documentation In-Tree

.gitignore

@@ -25,3 +25,4 @@ env
 
 # hex_core artifact
 apps/rebar/src/vendored/r3_safe_erl_term.erl
+apps/rebar/doc

README.md

@@ -26,12 +26,12 @@ Rebar3 will:
 - handle build artifacts, paths, and libraries such that standard
   development tools can be used without a headache;
 - adapt to projects of all sizes on almost any platform;
-- treat [documentation](https://rebar3.org/docs/) as a feature,
+- treat [documentation](https://hexdocs.pm/rebar3) as a feature,
   and errors or lack of documentation as a bug.
 
 Rebar3 is also a self-contained Erlang script. It is easy to distribute or
 embed directly in a project. Tasks or behaviours can be modified or expanded
-with a [plugin system](https://rebar3.org/docs/configuration/plugins)
+with a [plugin system](https://hexdocs.pm/rebar3/configuration/plugins.html)
 [flexible enough](https://github.com/lfe-rebar3/rebar3_lfe) that even other languages
 on the Erlang VM will use it as a build tool.
 
@@ -61,23 +61,23 @@ This list presents the known working version combos between Rebar3 and
 Erlang/OTP. Always use the latest version your project can tolerate for latest
 security fixes.
 
-| Rebar3 | Erlang/OTP Support Range | Notes
-|-       |-      | -
-| 3.25.1 | 26-28 | issues with newer Windows versions were reported on 3.25.0 and OTP-28
-| 3.24.0 | 25-27 |
-| 3.23.0 | 25-27 |
-| 3.22.1 | 25-27 |
-| 3.21.0 | 24-26 |
-| 3.20.0 | 23-25 |
-| 3.19.0 | 23-25 |
-| 3.18.0 | 22-24 |
-| 3.17.0 | 22-24 |
-| 3.16.1 | 22-24 | Don't use 3.16.0, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html
-| 3.15.2 | 19-23 | Don't use 3.15.0 or 3.15.1, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html
-| 3.14.1 | 19-23 |
-| 3.13.3 | 19-22 | Don't use 3.13.1 or 3.13.2, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html
-
-A [getting started guide is maintained on the official documentation website](https://rebar3.org/docs/getting-started),
+| Rebar3 | Erlang/OTP Support Range | Notes |
+|-       |-      | - |
+| 3.25.1 | 26-28 | issues with newer Windows versions were reported on 3.25.0 and OTP-28 |
+| 3.24.0 | 25-27 | |
+| 3.23.0 | 25-27 | |
+| 3.22.1 | 25-27 | |
+| 3.21.0 | 24-26 | |
+| 3.20.0 | 23-25 | |
+| 3.19.0 | 23-25 | |
+| 3.18.0 | 22-24 | |
+| 3.17.0 | 22-24 | |
+| 3.16.1 | 22-24 | Don't use 3.16.0, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html |
+| 3.15.2 | 19-23 | Don't use 3.15.0 or 3.15.1, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html |
+| 3.14.1 | 19-23 | |
+| 3.13.3 | 19-22 | Don't use 3.13.1 or 3.13.2, see https://ferd.ca/you-ve-got-to-upgrade-rebar3.html |
+
+A [getting started guide is maintained on the official documentation website](https://hexdocs.pm/rebar3/getting-started.html),
 but installing rebar3 can be done by any of the ways described below
 
 Latest stable compiled version:
@@ -122,7 +122,7 @@ Do note that if you are planning to work with multiple Erlang versions on the sa
 
 ## Documentation
 
-Rebar3 documentation is maintained on [https://rebar3.org/docs](https://rebar3.org/docs)
+Rebar3 documentation is maintained on [https://hexdocs.pm/rebar3](https://hexdocs.pm/rebar3)
 
 ## Features
 
@@ -138,35 +138,35 @@ others via the plugin ecosystem:
 | Clean up artifacts   | Remove the compiled beam files from a project with `rebar3 clean` or just remove the `_build` directory to remove *all* compilation artifacts |
 | Code Coverage        | Various commands can be instrumented to accumulate code coverage data (such as `eunit` or `ct`). Reports can be generated with `rebar3 cover` |
 | Common Test          | The test framework can be run by calling `rebar3 ct` |
-| Dependencies         | Rebar3 maintains local copies of dependencies on a per-project basis. They are fetched deterministically, can be locked, upgraded, fetched from source, packages, or from local directories. See [Dependencies on the documentation website](https://rebar3.org/docs/configuration/dependencies/). Call `rebar3 tree` to show the whole dependency tree. |
-| Documentation        | Print help for rebar3 itself (`rebar3 help`) or for a specific task (`rebar3 help <task>`). Full reference at [rebar3.org](https://rebar3.org/docs). |
+| Dependencies         | Rebar3 maintains local copies of dependencies on a per-project basis. They are fetched deterministically, can be locked, upgraded, fetched from source, packages, or from local directories. See [Dependencies on the documentation website](https://hexdocs.pm/rebar3/configuration/dependencies.html). Call `rebar3 tree` to show the whole dependency tree. |
+| Documentation        | Print help for rebar3 itself (`rebar3 help`) or for a specific task (`rebar3 help <task>`). Full reference at [rebar3 documentation](https://hexdocs.pm/rebar3). |
 | Dialyzer             | Run the Dialyzer analyzer on the project with `rebar3 dialyzer`. Base PLTs for each version of the language will be cached and reused for faster analysis |
 | Edoc                 | Generate documentation using edoc with `rebar3 edoc` |
 | Escript generation   | Rebar3 can be used to generate [escripts](http://www.erlang.org/doc/man/escript.html) providing an easy way to run all your applications on a system where Erlang is installed |
 | Eunit                | The test framework can be run by calling `rebar3 eunit` |
 | Locked dependencies  | Dependencies are going to be automatically locked to ensure repeatable builds. Versions can be changed with `rebar3 upgrade` or `rebar3 upgrade <app>`, or locks can be released altogether with `rebar3 unlock`. |
 | Packages             | A given [Hex package](https://hex.pm) can be inspected `rebar3 pkgs <name>`. This will output its description and available versions |
 | Path                 | While paths are managed automatically, you can print paths to the current build directories with `rebar3 path`. |
-| Plugins              | Rebar3 can be fully extended with [plugins](https://rebar3.org/docs/configuration/plugins/). List or upgrade plugins by using the plugin namespace (`rebar3 plugins`). |
-| Profiles             | Rebar3 can have subconfiguration options for different profiles, such as `test` or `prod`. These allow specific dependencies or compile options to be used in specific contexts. See [Profiles](https://rebar3.org/docs/configuration/profiles) in the docs. |
-| Releases             | Rebar3 supports [building releases](https://rebar3.org/docs/deployment/releases) with the `relx` tool, providing a way to ship fully self-contained Erlang systems. Release update scripts for live code updates can also be generated. |
+| Plugins              | Rebar3 can be fully extended with [plugins](https://hexdocs.pm/rebar3/plugins.html). List or upgrade plugins by using the plugin namespace (`rebar3 plugins`). |
+| Profiles             | Rebar3 can have subconfiguration options for different profiles, such as `test` or `prod`. These allow specific dependencies or compile options to be used in specific contexts. See [Profiles](https://hexdocs.pm/rebar3/configuration/profiles.html) in the docs. |
+| Releases             | Rebar3 supports [building releases](https://hexdocs.pm/rebar3/deployment/releases.html) with the `relx` tool, providing a way to ship fully self-contained Erlang systems. Release update scripts for live code updates can also be generated. |
 | Shell                | A full shell with your applications available can be started with `rebar3 shell`. From there, call tasks as `r3:do(compile)` to automatically recompile and reload the code without interruption |
 | Tarballs             | Releases can be packaged into tarballs ready to be deployed. |
-| Templates            | Configurable templates ship out of the box (try `rebar3 new` for a list or `rebar3 new help <template>` for a specific one). [Custom templates](https://rebar3.org/docs/tutorials/templates) are also supported, and plugins can also add their own. |
+| Templates            | Configurable templates ship out of the box (try `rebar3 new` for a list or `rebar3 new help <template>` for a specific one). [Custom templates](https://hexdocs.pm/rebar3/tutorials/templates.html) are also supported, and plugins can also add their own. |
 | Xref                 | Run cross-reference analysis on the project with [xref](http://www.erlang.org/doc/apps/tools/xref_chapter.html) by calling `rebar3 xref`. |
 
 ## Migrating From rebar2
 
 The grievances we had with Rebar 2.x were not fixable without breaking
 compatibility in some very important ways.
 
-A full guide titled [From Rebar 2.x to Rebar3](https://rebar3.org/docs/tutorials/from_rebar2_to_rebar3/)
+A full guide titled [From Rebar 2.x to Rebar3](https://hexdocs.pm/rebar3/tutorials/from_rebar2_to_rebar3.html)
 is provided on the documentation website.
 
 Notable modifications include mandating a more standard set of directory
 structures, changing the handling of dependencies, moving some compilers (such
 as C, Diameter, ErlyDTL, or ProtoBuffs) to
-[plugins](https://rebar3.org/docs/configuration/plugins) rather than
+[plugins](https://hexdocs.pm/rebar3/configuration/plugins.html) rather than
 maintaining them in core rebar, and moving release builds from reltool to
 relx.
 
@@ -181,13 +181,13 @@ If you need
 quick feedback, you can try the #rebar channel on
 [irc.freenode.net](https://freenode.net) or the #rebar3 channel on
 [erlanger.slack.com](https://erlanger.slack.com/). Be sure to check the
-[documentation](https://rebar3.org/docs) first, just to be sure you're not
+[documentation](https://hexdocs.pm/rebar3) first, just to be sure you're not
 asking about things with well-known answers.
 
 For bug reports, roadmaps, and issues, visit the [github issues
 page](https://github.com/erlang/rebar3/issues).
 
 General rebar community resources and links can be found at
-[rebar3.org/docs/about/about-us/#community](https://rebar3.org/docs/about/about-us/#community)
+[Community | About Us](https://hexdocs.pm/rebar3/about/about-us.html#community)
 
-To contribute to rebar3, please refer to [CONTRIBUTING](CONTRIBUTING.md).
+To contribute to rebar3, please refer to [CONTRIBUTING](https://github.com/erlang/rebar3/blob/master/CONTRIBUTING.md).

apps/rebar/src/cth_fail_fast.erl

@@ -1,4 +1,5 @@
 -module(cth_fail_fast).
+-moduledoc false.
 
 %% Callbacks
 -export([id/1]).

apps/rebar/src/cth_retry.erl

@@ -1,4 +1,5 @@
 -module(cth_retry).
+-moduledoc false.
 
 %% Callbacks
 -export([id/1]).

apps/rebar/src/rebar_agent.erl

@@ -290,9 +290,9 @@ reload_modules(Modules0) ->
     Modules = [M || M <- Modules0, is_changed(M)],
     reload_modules(Modules, erlang:function_exported(code, prepare_loading, 1)).
 
-%% @spec is_changed(atom()) -> boolean()
 %% @doc true if the loaded module is a beam with a vsn attribute
 %%      and does not match the on-disk beam file, returns false otherwise.
+-spec is_changed(atom()) -> boolean().
 is_changed(M) ->
     try
         module_vsn(M:module_info(attributes)) =/= module_vsn(code:get_object_code(M))

apps/rebar/src/rebar_file_utils.erl

@@ -86,7 +86,7 @@ consult_config(State, Filename) ->
     consult_config_terms(State, Config).
 
 %% @doc Reads a config file via consult_env_config/2 if the file name has
-%% the suffix `.src`, and with consult_config/2 otherwise
+%% the suffix `.src', and with consult_config/2 otherwise
 -spec consult_any_config(rebar_state:t(), file:filename()) -> [[tuple()]].
 consult_any_config(State, Filename) ->
     case is_src_config(Filename) of

docs/about/about-us.md

@@ -0,0 +1,16 @@
+# About Us
+## Community
+
+- [Issue Tracker](https://github.com/erlang/rebar3/issues)
+- [Github Discussions](https://github.com/erlang/rebar3/discussions)
+- Slack: #rebar3 on [Erlang Slack](https://erlef.org/slack-invite/erlanger)
+- IRC: #rebar on freenode
+- [Contribution guidelines](https://github.com/erlang/rebar3/blob/master/CONTRIBUTING.md)
+
+## Credits
+
+- [Source Contributors](https://github.com/rebar/rebar3/blob/master/THANKS) *(including rebar 2.x contributors prior to forking)*
+- Rebar3 logo by [Francis Tseng](https://twitter.com/frnsys).
+- Maintainers with admin rights:
+  - [@tsloughter](https://github.com/tsloughter/)
+  - [@ferd](https://github.com/ferd/)

docs/about/security-policy.md

@@ -0,0 +1,45 @@
+# Security Policy
+## Security Caveats
+
+Rebar3 is a build tool that by design allows arbitrary code execution from downloaded components. Scripts can be executed in all kinds of areas of a regular project workflow including (but not limited to): scripts to modify configuration files, "parse transforms" (macros), plugins, provider and shell hooks, and so on.
+
+Users of Rebar3 should be aware of the nature of its model, and issues related to these parts of its design will not be considered to be security issues nor vulnerabilities.
+
+## Reporting a Security Issue
+
+All security issues should be reported to one or more of the current maintainers:
+
+- [Fred Hebert](https://keybase.io/mononcqc) ([@ferd](https://github.com/ferd/))
+- [Tristan Sloughter](https://keybase.io/tsloughter) ([@tsloughter](https://github.com/tsloughter/))
+
+E-Mail addresses are available in GitHub profiles, and PGP public keys in Keybase profiles.
+
+If you have not received a reply to your query within 48 hours, or have not heard from one of the maintainers for the past five days, there are a few steps you can take:
+
+- One of the authenticated channels in the maintainers Keybase profiles
+- Open a GitHub issue directly
+- Ask on #rebar3 on the [official Erlang Slack team](https://erlef.org/slack-invite/erlanger)
+- Ask on #rebar on IRC on libera.chat
+
+Please note that the GitHub issues, mailing list, and chat channels are public areas. When escalating in these venues, please do not discuss details of your issue. Simply say that you’re trying to get a hold of someone from the maintainer team.
+
+## Disclosure Policy
+
+We're a small project of volunteers working in whatever free time they have, with limited mechanisms to reach developers from other communication channels.
+
+Disclosure will be fairly ad-hoc and made to reach as many people as possible.
+
+Nevertheless, the expected steps are:
+
+1. The issue is received and discussed privately by the maintainers
+2. A fix is prepared and reviewed between maintainers
+3. When ready, the fix will be committed to the repository and a release will be cut
+4. An announcement will be made about the new release on the public channels associated to the project
+
+## Receiving Security Updates
+
+The best way to know about security updates is to subscribe to any of the communication channels of the project.
+
+## Comments on This Policy
+
+If you have any suggestions to improve this policy, please contact the maintainers or open a GitHub issue.