Skip to content

Commit 4ab1d5a

Browse files
authored
Review CHANGELOG and docs for upcoming RC (#9100)
1 parent 78ce679 commit 4ab1d5a

File tree

3 files changed

+86
-12
lines changed

3 files changed

+86
-12
lines changed

CHANGELOG.md

Lines changed: 72 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,63 @@
11
# Changelog for Elixir v1.9
22

3+
## Releases
4+
5+
The main feature in Elixir v1.9 is the addition of releases. A release is a self-contained directory that consists of your application code, all of its dependencies, plus the whole Erlang Virtual Machine (VM) and runtime. Once a release is assembled, it can be packaged and deployed to a target as long as the target runs on the same operating system (OS) distribution and version as the machine running the `mix release` command.
6+
7+
You can start a new project and assemble a release for it in three easy steps:
8+
9+
$ mix new my_app
10+
$ cd my_app
11+
$ MIX_ENV=prod mix release
12+
13+
A release will be assembled in `_build/prod/rel/my_app`. Inside the release, there will be a `bin/my_app` file which is the entry point to your system. It supports multiple commands, such as:
14+
15+
* `bin/my_app start`, `bin/my_app start_iex`, `bin/my_app restart`, and `bin/my_app stop` - for general management of the release
16+
17+
* `bin/my_app rpc COMMAND` and `bin/my_app remote` - for running commands on the running system or to connect to the running system
18+
19+
* `bin/my_app eval COMMAND` - to start a fresh system that runs a single command and then shuts down
20+
21+
* `bin/my_app daemon` and `bin/my_app daemon_iex` - to start the system as a daemon on Unix-like systems
22+
23+
* `bin/my_app install` - to install the system as a service on Windows machines
24+
25+
### Why releases?
26+
27+
Releases allow developers to precompile and package all of their code and the runtime into a single unit. The benefits of releases are:
28+
29+
* Code preloading. The VM has two mechanisms for loading code: interactive and embedded. By default, it runs in the interactive mode which dynamically loads modules when they are used for the first time. The first time your application calls `Enum.map/2`, the VM will find the `Enum` module and load it. There’s a downside. When you start a new server in production, it may need to load many other modules, causing the first requests to have an unusual spike in response time. Releases run in embedded mode, which loads all available modules upfront, guaranteeing your system is ready to handle requests after booting.
30+
31+
* Configuration and customization. Releases give developers fine grained control over system configuration and the VM flags used to start the system.
32+
33+
* Self-contained. A release does not require the source code to be included in your production artifacts. All of the code is precompiled and packaged. Releases do not even require Erlang or Elixir in your servers, as they include the Erlang VM and its runtime by default. Furthermore, both Erlang and Elixir standard libraries are stripped to bring only the parts you are actually using.
34+
35+
* Multiple releases. You can assemble different releases with different configuration per application or even with different applications altogether.
36+
37+
### Hooks and Configuration
38+
39+
Releases also provide built-in hooks for configuring almost every need of the production system:
40+
41+
* `config/config.exs` (and `config/prod.exs`) - provides build-time application configuration, which is executed when the release is assembled
42+
43+
* `config/releases.exs` - provides runtime application configuration. It is executed every time the release boots and is further extensible via config providers
44+
45+
* `rel/vm.args.eex` - a template file that is copied into every release and provides static configuration of the Erlang Virtual Machine and other runtime flags
46+
47+
* `rel/env.sh.eex` and `rel/env.bat.eex` - template files that are copied into every release and executed on every command to set up environment variables, including ones specific to the VM, and the general environment
48+
49+
We have written extensive documentation on releases, so we recommend checking it out for more information.
50+
51+
## Configuration overhaul
52+
53+
A new `Config` module has been added to Elixir. The previous configuration API, `Mix.Config`, was part of the Mix build tool. But since releases provide runtime configuration and Mix is not included in releases, we ported the `Mix.Config` API to Elixir. In other words, `use Mix.Config` has been soft-deprecated in favor of `import Config`.
54+
55+
Another important change related to configuration is that `mix new` will no longer generate a `config/config.exs` file. [Relying on configuration is undesired for most libraries](https://hexdocs.pm/elixir/library-guidelines.html#avoid-application-configuration) and the generated config files pushed library authors in the wrong direction. Furthermore, `mix new --umbrella` will no longer generate a configuration for each child app, instead all configuration should be declared in the umbrella root. That's how it has always behaved, we are now making it explicit.
56+
57+
## Other enhancements
58+
59+
There are many other enhancements. The Elixir CLI got a handful of new options in order to best support releases. `Logger` now computes its sync/async/discard thresholds in a decentralized fashion, reducing contention. `EEx` templates support more complex expressions than before. Finally, there is a new `~U` sigil for working with UTC DateTimes as well as new functions in the `File`, `Registry`, and `System` modules.
60+
361
## v1.9.0-dev
462

563
### 1. Enhancements
@@ -15,9 +73,9 @@
1573
* [Code] Add `static_atom_encoder` option to `Code.string_to_quoted/2`
1674
* [Code] Support `:force_do_end_blocks` on `Code.format_string!/2` and `Code.format_file!/2`
1775
* [Code] Do not raise on deadlocks on `Code.ensure_compiled/1`
18-
* [Config] Add `Config`, `Config.Reader` and `Config.Provider` modules for working with configuration
76+
* [Config] Add `Config`, `Config.Reader`, and `Config.Provider` modules for working with configuration
1977
* [File] Add `File.rename!/2`
20-
* [Inspect] Add `:inspect_fun` to `Inspect.Opts`
78+
* [Inspect] Add `:inspect_fun` and `:custom_options` to `Inspect.Opts`
2179
* [Kernel] Add `~U` sigil for UTC date times
2280
* [Kernel] Optimize `&super/arity` and `&super(&1)`
2381
* [Kernel] Optimize generated code for `with` with a catch-all clause
@@ -26,6 +84,7 @@
2684
* [Protocol] Improve `Protocol.UndefinedError` messages to also include the type that was attempted to dispatch on
2785
* [Protocol] Optimize performance of dynamic dispatching for non-consolidated protocols
2886
* [Record] Include field names in generated type for records
87+
* [Regex] Automatically recompile regexes
2988
* [Registry] Add `Registry.select/2`
3089
* [System] Add `System.restart/0`, `System.pid/0` and `System.no_halt/1`
3190
* [System] Add `System.get_env/2`, `System.fetch_env/1`, and `System.fetch_env!/1`
@@ -35,12 +94,12 @@
3594

3695
* [ExUnit] Allow multiple `:exclude` on configuration/CLI
3796
* [ExUnit.DocTest] No longer wrap doctest errors in custom exceptions. They ended-up hiding more information than showing
38-
* [ExUnit.DocTest] Display the actual doctest code when doctset fails
97+
* [ExUnit.DocTest] Display the actual doctest code when doctest fails
3998

4099
#### IEx
41100

42-
* [IEx.CLI] Copy ticktime from remote node on IEx --remsh
43-
* [IEx.CLI] Automatically add a host on node given to --remsh
101+
* [IEx.CLI] Copy ticktime from remote node on IEx `--remsh`
102+
* [IEx.CLI] Automatically add a host on node given to `--remsh`
44103

45104
#### Logger
46105

@@ -75,22 +134,29 @@
75134
* [Kernel] Keep order of elements when macro `in/2` is expanded with a literal list on the right-hand side
76135
* [Kernel] Print proper location on undefined function error from dynamically generated functions
77136
* [System] Make sure `:init.get_status/0` is set to `{:started, :started}` once the system starts
137+
* [Path] Do not expand `~` in `Path.expand/2` when not followed by a path separator
78138
* [Protocol] Ensure `debug_info` is kept in protocols
79139
* [Regex] Ensure inspect returns valid `~r//` expressions when they are manually compiled with backslashes
80140
* [Registry] Fix ETS leak in `Registry.register/2` for already registered calls in unique registries while the process is still alive
81141

82142
#### ExUnit
83143

84144
* [ExUnit] Raise error if attempting to run single line tests on multiple files
145+
* [ExUnit] Return proper error on duplicate child IDs on `start_supervised`
85146

86147
#### IEx
87148

88149
* [IEx] Automatically shut down IEx if we receive EOF
89150

151+
#### Logger
152+
153+
* [Logger] Don't discard Logger messages from other nodes as to leave a trail on both systems
154+
90155
#### Mix
91156

92157
* [mix compile] Ensure Erlang-based Mix compilers (erlang, leex, yecc) set valid position on diagnostics
93158
* [mix compile] Ensure compilation halts in an umbrella project if one of the siblings fail to compile
159+
* [mix deps] Raise an error if the umbrella app's dir name and `mix.exs` app name don't match
94160
* [mix test] Do not consider modules that are no longer cover compiled when computing coverage report, which could lead to flawed reports
95161

96162
### 3. Soft-deprecations (no warnings emitted)
@@ -105,6 +171,7 @@
105171

106172
* [CLI] Deprecate `--detached` option, use `--erl "-detached"` instead
107173
* [Map] Deprecate Enumerable keys in `Map.drop/2`, `Map.split/2`, and `Map.take/2`
174+
* [String] The `:insert_replaced` option in `String.replace/4` has been deprecated. Instead you may pass a function as a replacement or use `:binary.replace/4` if you need to support earlier Elixir versions
108175

109176
#### Mix
110177

lib/elixir/pages/Compatibility and Deprecations.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Elixir deprecations happen in 3 steps:
6363

6464
1. The feature is soft-deprecated. It means both CHANGELOG and documentation must list the feature as deprecated but no warning is effectively emitted by running the code. There is no requirement to soft-deprecate a feature.
6565

66-
2. The feature is effectively deprecated by emitting warnings on usage. This is also known as hard-deprecation. In order to deprecate a feature, the proposed alternative MUST exist for AT LEAST two minor versions. For example, `Enum.uniq/2` was soft-deprecated in favor of `Enum.uniq_by/2` in Elixir v1.1. This means a deprecation warning may only be emitted by Elixir v1.3 or later.
66+
2. The feature is effectively deprecated by emitting warnings on usage. This is also known as hard-deprecation. In order to deprecate a feature, the proposed alternative MUST exist for AT LEAST THREE minor versions. For example, `Enum.uniq/2` was soft-deprecated in favor of `Enum.uniq_by/2` in Elixir v1.1. This means a deprecation warning may only be emitted by Elixir v1.4 or later.
6767

6868
3. The feature is removed. This can only happen on major releases. This means deprecated features in Elixir v1.x shall only be removed by Elixir v2.x.
6969

@@ -73,6 +73,8 @@ The first column is the version the feature was hard deprecated. The second colu
7373

7474
Version | Deprecated feature | Replaced by (available since)
7575
:-------| :-------------------------------------------------- | :---------------------------------------------------------------
76+
[v1.9] | Passing `:insert_replaced` to `String.replace/4` | Use `:binary.replace/4` (v1.0)
77+
[v1.9] | Enumerable keys in `Map.drop/2`, `Map.split/2`, and `Map.take/2` | Call `Enum.to_list/1` on the second argument before hand (v1.0)
7678
[v1.9] | `Mix.Project.load_paths/1` | `Mix.Project.compile_path/1` (v1.0)
7779
[v1.9] | `--detached` in CLI | `--erl "-detached"` (v1.0)
7880
[v1.8] | Passing a non-empty list to `Enum.into/2` | `Kernel.++/2` or `Keyword.merge/2` (v1.0)

lib/mix/lib/mix/tasks/release.ex

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -539,15 +539,20 @@ defmodule Mix.Tasks.Release do
539539
and configuring the running system:
540540
541541
* `config/config.exs` (and `config/prod.exs`) - provides build-time
542-
application configuration
542+
application configuration, which are executed when the release is
543+
assembled
543544
544-
* `config/releases.exs` - provides runtime application configuration
545+
* `config/releases.exs` - provides runtime application configuration.
546+
It is executed every time the release boots and is further extensible
547+
via config providers
545548
546-
* `rel/vm.args.eex` - provides a static mechanism for configuring the
547-
Erlang Virtual Machine and other runtime flags
549+
* `rel/vm.args.eex` - a template file that is copied into every release
550+
and provides static configuration of the Erlang Virtual Machine and
551+
other runtime flags
548552
549-
* `rel/env.sh.eex` and `rel/env.bat.eex`- provides a dynamic mechanism
550-
for setting up the VM, runtime flags, and environment variables
553+
* `rel/env.sh.eex` and `rel/env.bat.eex` - template files that are copied
554+
into every release and are executed on every command to set up environment
555+
variables, including specific ones to the VM, and the general environment
551556
552557
## Directory structure
553558

0 commit comments

Comments
 (0)