Merge branch 'release/1.12'

docs/README.md

@@ -114,11 +114,12 @@ Instructions on how to use the compiler and tools.
   </div>
   <div class="card" markdown="1">
 
-### Developer News
+### Project and Releases Information
 
 Announcements about the language development.
 
-* [Release Notes](https://crystal-lang.org/blog/#release_notes)
+* [Release Notes](https://crystal-lang.org/releases)
+* [Release Policy](project/release-policy.md)
 * [Crystal Blog](https://crystal-lang.org/blog)
 
   </div>

docs/SUMMARY.md

@@ -100,9 +100,9 @@
         * [instance_alignof](syntax_and_semantics/instance_alignof.md)
         * [offsetof](syntax_and_semantics/offsetof.md)
         * [Uninitialized variable declaration](syntax_and_semantics/declare_var.md)
+        * [asm](syntax_and_semantics/asm.md)
     * [Compile-time flags](syntax_and_semantics/compile_time_flags.md)
         * [Cross-compilation](syntax_and_semantics/cross-compilation.md)
-        * [Platform Support](syntax_and_semantics/platform_support.md)
     * [C bindings](syntax_and_semantics/c_bindings/README.md)
         * [lib](syntax_and_semantics/c_bindings/lib.md)
         * [fun](syntax_and_semantics/c_bindings/fun.md)
@@ -151,3 +151,5 @@
     * [Using the Compiler](man/crystal/README.md)
     * [The Shards Command](man/shards/README.md)
     * [Required libraries](man/required_libraries.md)
+    * [Platform Support](syntax_and_semantics/platform_support.md)
+    * [Release Policy](project/release-policy.md)

docs/guides/testing.md

@@ -196,6 +196,8 @@ crystal spec --tag 'fast'
 crystal spec --tag '~slow'
 ```
 
+There are additional options for running specs by name, adjusting output formats, doing dry-runs, etc, see [Using the compiler](../man/crystal/README.md#crystal-spec).
+
 ## Spec helper
 
 Many projects use a custom spec helper file, usually named `spec/spec_helper.cr`.

docs/man/crystal/README.md

@@ -291,14 +291,15 @@ $ crystal env CRYSTAL_VERSION
 The `crystal spec` command compiles and runs a Crystal spec suite.
 
 ```
-crystal spec [<options>] [<file>...] [-- [<runner_options>]]
+crystal spec [<options>] [<file>[:line] | <folder>]... [-- [<runner_options>]]
 ```
 
 All `files` arguments are concatenated into a single Crystal source. If an argument points to a folder, all spec
-files inside that folder are appended. If no `files` argument is provided, the default is `./spec`. A filename can be suffixed by `:`
-and a line number, providing this location to the `--location` runner option (see below).
+files inside that folder (and its recursive subfolders) named `*_spec.cr` are appended.
+If no `files` argument is provided, the default is the `./spec` folder.
+A filename can be suffixed by `:` and a line number, providing this location to the `--location` runner option (see below).
 
-Run `crystal spec --options` for available options.
+Run `crystal spec --options` for available preceding options.
 
 **Runner options:**
 
@@ -316,7 +317,7 @@ the other arguments by a double dash (`--`).
 * `--dry-run`: Passes all tests without actually executing them.
 * `--help`, `-h`: Prints help and exits.
 
-The following options can be combined to filter the list of specs to run.
+The following runner options can be combined to filter the list of specs to run.
 
 * `--example <name>`, `-e <name>`: Runs examples whose full nested names include `<name>`.
 * `--line <line>`, `-l <line>`: Runs examples whose line matches `<line>`.

docs/project/release-policy.md

@@ -0,0 +1,43 @@
+# Release Policy
+
+Crystal releases have a version indicated by a major, minor and patch number.
+
+The current major branch number is `1`.
+
+New features are added in minor releases (`1.x.0`) which are regularly scheduled every three months.
+
+Patch releases contain only important bug fixes and are released when necessary.
+They usually only appear for the latest minor branch.
+
+New releases are announced at [crystal-lang.org/releases](https://crystal-lang.org/releases) ([RSS feed](https://crystal-lang.org/releases)).
+
+There are currently no plans for a new major release.
+
+## Backwards compatibility
+
+Minor and patch releases are backwards compatible: Well-defined behaviours and documented APIs in a given version
+will continue working on future versions within the same major branch.
+
+As a result, migrating to a new minor release is usually seamless.
+
+### Reservations
+
+Although we expect the vast majority of programs to remain compatible over time,
+it is impossible to guarantee that no future change will break any program.
+Under some unlikely circumstances, we may introduce changes that break existing code.
+Rest assured we are commited to keep the impact as minimal as possible.
+
+* Security: a security issue in the implementation may arise whose resolution requires backwards incompatible changes. We reserve the right to address such security issues.
+
+* Bugs: if an API has undesired behaviour, a program that depends on the buggy behaviour may break if the bug is fixed. We reserve the right to fix such bugs.
+
+* Compiler front-end: improvements may be done to the compiler, introducing new warnings for ambiguous modes and providing more detailed error messages. Those can lead to compilation errors (when building with `--error-on-warnings`) or tooling failures when asserting on specific error messages (although one should avoid such). We reserve the right to do such improvements.
+
+* Feature additions: When introducing new features into the language or core library, there can be collisions with the names of types, methods, etc. defined in user code. We reserve the right to add new names when necessary.
+
+The changelog and release notes highlight any changes that have a considerable potential for breaking existing code, even if it uses experimental, undocumented or unsupported features.
+
+### Experimental features
+
+The only exception to the compatibility guarantees are experimental features, which are explicitly designated as such with the [`@[Experimental]`](https://crystal-lang.org/api/Experimental.html) annotation.
+There is no compatibility guarantee until they are stabilized (at which point the annotation is dropped).

docs/syntax_and_semantics/asm.md

@@ -0,0 +1,38 @@
+# asm
+
+The `asm` keyword can be used to insert inline assembly, which is needed for a very small set of features such as fiber switching and system calls:
+
+```crystal
+# x86-64 targets only
+dst = 0
+asm("mov $$1234, $0" : "=r"(dst))
+dst # => 1234
+```
+
+An `asm` expression consists of up to 5 colon-separated sections, and components inside each section are separated by commas. For example:
+
+```crystal
+asm(
+  # the assembly template string, following the
+  # syntax for LLVM's integrated assembler
+  "nop" :
+  # output operands
+  "=r"(foo), "=r"(bar) :
+  # input operands
+  "r"(1), "r"(baz) :
+  # names of clobbered registers
+  "eax", "memory" :
+  # optional flags, corresponding to the LLVM IR
+  # sideeffect / alignstack / inteldialect / unwind attributes
+  "volatile", "alignstack", "intel", "unwind"
+)
+```
+
+Only the template string is mandatory, all other sections can be empty or omitted:
+
+```crystal
+asm("nop")
+asm("nop" :: "b"(1), "c"(2)) # output operands are empty
+```
+
+For more details, refer to the [LLVM documentation's section on inline assembler expressions](https://llvm.org/docs/LangRef.html#inline-assembler-expressions).