docs: prepare changelog for Teal 0.24.0

CHANGELOG.md

@@ -1,3 +1,123 @@
+# 0.24.0 - Teal Spring '24
+
+2024-10-07
+
+This a big release! It is a culmination of work that has spanned multiple
+years, and it would not be possible without the amazing feedback given by
+the community on the `next` branch, where this was developed. This release
+does include that "lot of new code" that I wanted to merge in the "near
+future", as stated in the previous release's changelog.
+
+The main feature is the addition of interfaces, which introduces a model for
+subtyping table types in the language. That should allow for representing the
+various kinds of object models that are used across the Lua ecosystem, without
+promoting any particular class/object system over the others.
+
+This release features commits by François Perrad, Victor Ilchev and Hisham
+Muhammad.
+
+## What's New
+
+### Language
+
+* **Interfaces**: you can now declare abstract interfaces, and record types
+ can implement them. This allows you to declare subtyping relations, and
+ better support inheritance models (e.g. `local record Circle is Shape`).
+ * Records and interfaces may declare a `where` clause with an expression
+ over `self`, which allows the `is` operator to discriminate the type.
+ * With discriminated record types, it is now possible to declare unions
+ over multiple record types.
+ * "Arrayrecords" are no longer a distinct type: they are just records
+ that implement an array interface (e.g. `local record R is {T}`)
+ * Type variables in functions can now have constraints on interfaces
+ (e.g. `function my_func<F is MyInterface>(...)`)
+ * `self` is now a valid type that can be used when declaring arguments
+ in functions declared in interfaces and records
+ * When a record is declared to be a subtype of an interface using `is`,
+ any function arguments using `self` in the parent interface type will
+ then resolve to the child record's type.
+* **Optional/required arguments in function calls** - functions may declare
+ arguments as optional, affecting the required arity of function calls.
+ The rightmost arguments of a function can have their variable names
+ annotated with a `?` sign, indicating that the argument does not need
+ to be passed in a function call. This refers only to the presence of the
+ argument in a call, and not to its type or nullability: a required
+ argument may still be called with an explicit `null`, but an optional
+ argument may be elided.
+ * In previous versions of Teal, all function arguments were effectively
+ optional. This means that Teal is now stricter which checking for
+ function calls. You can use `--feat-arity=off` in the command line
+ or `feat_arity = "off"` in `tlconfig.lua` to obtain the previous
+ behavior.
+ * To convert code that uses the old arity checking rules to the new
+ behavior, you can also use compiler pragmas in the code,
+ `--#pragma arity off` and `--#pragma arity off` to disable or enable
+ stricter arity checks.
+* **Macro expressions**: you can declare a restricted form of function called
+ a `macroexp`, which is always expanded inline. These can also be used
+ to declare compile-time metamethods, which expand without requiring
+ a metatable at runtime. The `where` clauses used in interfaces and
+ records are syntax sugar for macro expressions that implement a
+ pseudo-metamethod `__is`.
+* Dynamic `require` calls that do not take a module name as a literal
+ string are now allowed, and return `any`; you can load a static type
+ definition using `local type MyType = require("...")` and then cast
+ your dynamic require like so: `local my_mod = require(var) as MyType`
+* The type system is more nominal: all named types are now treated nominally,
+ except for unions, which are always type aliases. Previously record types
+ were nominal, but a named typed that resolved to a primitive such as
+ `integer` was structural. There are still subleties on the rules for when
+ a `local type` produces a new distinct type or an alias; they are
+ [explained in the docs](docs/aliasing.md).
+* The `<total>` attribute for variables can now only be applied when
+ initializing variables with literal tables. This is a minor breaking change,
+ but the usefulness of this attribute in other cases was very limited,
+ and it also produced misleading results.
+* Improved type signatures in the standard library
+ * `select` produces variadic returns
+
+### API
+
+* Simplified API in the `tl` module.
+ * The 0.15 API is still supported for backwards compatibility.
+
+### Tooling
+
+* `tl build` was removed. [Cyan](https:/teal-language/cyan)
+ should be used instead as the build tool for Teal projects.
+
+### Fixes
+
+* Fix commits included in this release refer both to bugs present
+ in the `master` branch as well as fixes specific to the 0.24 series,
+ reported by the community during the beta testing of this release.
+ The Git history and the GitHub issues list contain a more detailed
+ accounting of the bugfixes that went into this release.
+ Some of the fixes include:
+ * `tl check` now reports if the input file does not exist.
+ * Reporting location of the end of an `if` block correctly.
+ * No longer crash if a `require()` epression fails to resolve (#778).
+ * `tl types` now reports the types of variables in `for` loops.
+ * Improved error message when calling functions with insufficient
+ arguments.
+ * Disallowing using a base type as a type variable name.
+ * Type arguments resolving correctly in recursive functions.
+ * Type arguments resolving correctly in nested records (#754).
+ * `or` type inference between types with a subtyping relation
+ resolves to whichever is the larger type.
+ * Reporting an error if an iterator used in a generic `for` does not
+ declare a return value type (#736).
+ * When checking `<total>` values, no longer reporting record
+ function and metamethods as missing fields (#749).
+ * Localizing a record no longer makes the local a type (#759).
+ * Bad assignments of record tables are reported (#752).
+ * Nominal type alias declarations work as expected (#238).
+ * Nominals with generics can be resolved correcty (#777).
+ * Nested types are not closed too early (#775).
+ * Not failing when resolving nested empty tables.
+ * Exporting generics and type aliases from modules correctly
+ using `return` at the toplevel (#804).
+
 # 0.15.3
 
 2023-11-05