aws/jsii repository, the exact requirements for what should be included in the pull request vary depending
on the type of update that is proposed:
-
Changing Behavior describes the process to be followed when introducing changes to the
+
Changing Behavior describes the process to be followed when introducing changes to the
behavior of any component of jsii: new features, breaking changes to existing features, ...
-
Addressing Gaps is the process used for adding specification around existing but unspecified
+
Addressing Gaps is the process used for adding specification around existing but unspecified
behavior.
-
Trivial Changes explains how to propose changes that improve the specification without changing
+
Trivial Changes explains how to propose changes that improve the specification without changing
its meaning.
-
Changing Behavior
+
Changing Behavior
If the change is not backwards compatible (it is a breaking change to an existing feature, or it is a new feature
that requires all runtime libraries implement support immediately), a new RFC should be created in the
awslabs/aws-cdk-rfcs repository, following the RFC Process. This ensures enough time is
@@ -1987,7 +1987,7 @@
Addressing Gaps
+
Addressing Gaps
Proposals that increase the specification's coverage (desribing behavior that already exists) are handled as GitHub pull
requests that must contain the following elements:
@@ -1997,7 +1997,7 @@
Trivial Changes
+
Trivial Changes
Proposal of trivial changes, such as correcting typos in the document, or re-phrasing elements of the specification
without altering the meaning (typically to improve clarity) are handled in a simple GitHub pull request.
can be passed by value or by reference, depending on the type of the value as well as the declared type of the transfer
point (method return type, property type, argument type, ...).
The table below describes the serialization behavior applied for each possible declared type (rows) for a value of a
-given dynamic type (columns). The sign expresses cases that are illegal and should cause immediate failure. The term
+given dynamic type (columns). The sign expresses cases that are illegal and should cause immediate failure. The term
primitive encompasses boolean, string, and number.
timeline (the exact timeline may vary significantly depending on the specifics of the language being added).
The estimated total duration for the process is 4 to 6 months.
Planning
-
Estimated Duration: 2 weeks
+
Estimated Duration: 2 weeks
The first step is to study the jsii specification, as well as existing language implementations, in order to have the
knowledge necessary to write a new language support proposal RFC. The RFC document produced will evolve and be
polished as development of the new language support progresses, but the following elements must be present before any
@@ -1848,7 +1848,7 @@
Planning
Toolchain and platform requirements
Code Generation (jsii-pacmak)
-
Estimated Duration: 4 to 6 weeks
+
Estimated Duration: 4 to 6 weeks
The necessary code must be added to [jsii-pacmak] in order to map the jsii assembly's declared types into the
proposed language. While this code ought to leverage the new language's host runtime library, we begin with writing
the code generator in order to ensure the appropriate developer experience is achieved in the new language before
@@ -1858,7 +1858,7 @@
Code Generation (jsii-pacmak)<
identifiers are used in TypeScript code that require slugification or escaping in the target language (and will
hence cause a degraded developer experience).
Runtime Library
-
Estimated Duration: 4 to 6 weeks
+
Estimated Duration: 4 to 6 weeks
Now that the appropriate developer experience has been identified, the host runtime library supporting the generated
code can be written. This component must be written in the new language.
@@ -1867,7 +1867,7 @@
Runtime Library
behavior across all the runtimes, reducing the cost of maintaining many of those.
Building & Packaging
-
Estimated Duration: 2 weeks
+
Estimated Duration: 2 weeks
Once code is generated and it has a host runtime library to rely on, [jsii-pacmak] needs to receive the additional
logic required to compile and package the generated libraries as required, producing ready-to-publish artifacts.
The necessary toolchain needs to be added to the [public.ecr.aws/jsii/superchain] Docker image, so that jsii customers can rely
@@ -1875,18 +1875,18 @@
Building & Packaging
In addition to this, standardized Amazon CodePipeline actions need to be developed in order to support publishing to
the relevant idiomatic package managers.
Compliance Tests
-
Estimated Duration: 6 weeks
+
Estimated Duration: 6 weeks
The full standard compliance suite must be implemented for the new language. Leveraging the new code generator, host
runtime library and compilation logic, the tests demonstrate that the new library behaves consistently with all other
language bindings.
While it is possible to declare developer preview on a new language before all the tests pass, full compliance is a
pre-requisite to declaring general availability of the new language.
Documentation
-
Estimated Duration: 1 week
+
Estimated Duration: 1 week
The necessary documentation needs to be provided to support customers who want to onboard the new language. This also
includes updating [jsii-config] with support for the new languages' configuration block.
Developer Preview
-
Recommended Duration: 4 to 8 weeks
+
Recommended Duration: 4 to 8 weeks
It is possible to declare Developer Preview for a new language support as soon as the code generation and host
runtime library are mature enough to be useful, and cover the majority of use-cases. While certain edge-cases may still
be uncovered at the beginning of Developer Preview, a clear plan should exist that ensures a path exists to address
@@ -1929,7 +1929,7 @@
This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
+
This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
through early adopters. Use at your own risk, and please any report bugs.
Provide this setting, to use a user-provided typescript configuration with jsii. Set to the name of the tsconfig
@@ -2443,7 +2443,7 @@
validateTsconfig
Available from jsii >= 5.2
Warn
-
This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
+
This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
through early adopters. Use at your own risk, and please any report bugs.
A user-provider typescript config must follow certain rules to be a valid config for use with jsii.
@@ -2458,7 +2458,7 @@
validateTsconfig
-
strict
+
strict
(Default) Validates the provided config against a strict rule set designed for widespread support and backwards-compatibility.
@@ -2466,17 +2466,17 @@
validateTsconfig
Enforces a tsconfig as if it were generated by jsii. Use this to stay compatible with the generated config, but have full ownership over the file.
-
minimal
+
minimal
Only reject options that are known to be incompatible with jsii. This rule set is likely to be incomplete and new rules will be added without notice as incompatibilities are discovered.
-
off
+
off
Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk.
-
Recommended setting\
- Resulting jsii assembly/package may be incompatible with wider ecosystem
+
Recommended setting\
+ Resulting jsii assembly/package may be incompatible with wider ecosystem
There is currently no easy way to inspect these rule sets, however detailed error messages are returned if a provided tsconfig fails validation.
{"jsii":{
@@ -2554,7 +2554,7 @@
Dependencies that are not
- 2024-10-21
+ 2024-11-04
diff --git a/user-guides/lib-author/configuration/targets/dotnet/index.html b/user-guides/lib-author/configuration/targets/dotnet/index.html
index 37e73ad3d3..37f0d1a25a 100644
--- a/user-guides/lib-author/configuration/targets/dotnet/index.html
+++ b/user-guides/lib-author/configuration/targets/dotnet/index.html
@@ -20,7 +20,7 @@
-
+
@@ -1692,7 +1692,7 @@
Supported: Long Term Support (LTS) releases (those with an even major version) are
+
Supported: Long Term Support (LTS) releases (those with an even major version) are
supported and bugs specific to those releases are addressed with the highest priority. Every jsii release is
automatically tested against those releases.
-
Best effort: Development releases (those with an odd major version) are supported on a
+
Best effort: Development releases (those with an odd major version) are supported on a
best-effort basis. Some of these releases may include breaking changes or bugs that may cause runtime errors
that we may not be able to fix.
Releases not in the matrix might work, but are not guaranteed to: they can be considered to fall under the
- Best Effort umbrella, unless they are end-of-life. Releases past end-of-life are unlikely to work,
+ Best Effort umbrella, unless they are end-of-life. Releases past end-of-life are unlikely to work,
or may stop working with any future release.
The node releases schedule provides up-to-date information on the current status of all active
releases, and indicates the timelines for support (including planned End-of-Life dates for each).
option to only warn about reserved words of languages that are configured
for the current project.
-
Experimental Features
+
Experimental Features
Danger
The features discussed in this section are experimental. Their behavior may
@@ -1920,7 +1920,7 @@
--tsconfig
-
strict
+
strict
(Default) Validates the provided config against a strict rule set designed for widespread support and backwards-compatibility.
@@ -1928,17 +1928,17 @@
--tsconfigEnforces a tsconfig as if it were generated by jsii. Use this to stay compatible with the generated config, but have full ownership over the file.
-
minimal
+
minimal
Only reject options that are known to be incompatible with jsii. This rule set is likely to be incomplete and new rules will be added without notice as incompatibilities are discovered.
-
off
+
off
Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk.
-
Recommended setting\
- Resulting jsii assembly/package may be incompatible with wider ecosystem
+
Recommended setting\
+ Resulting jsii assembly/package may be incompatible with wider ecosystem
There is currently no easy way to inspect these rule sets, however detailed error messages are returned if a provided tsconfig fails validation.
--strip-deprecated
The --strip-deprecated option modifies the compilation flow such that all
@@ -2000,7 +2000,7 @@
Supported: Long Term Support (LTS) releases (those with an even major version) are
+
Supported: Long Term Support (LTS) releases (those with an even major version) are
supported and bugs specific to those releases are addressed with the highest priority. Every jsii release is
automatically tested against those releases.
-
Best effort: Development releases (those with an odd major version) are supported on a
+
Best effort: Development releases (those with an odd major version) are supported on a
best-effort basis. Some of these releases may include breaking changes or bugs that may cause runtime errors
that we may not be able to fix.
Releases not in the matrix might work, but are not guaranteed to: they can be considered to fall under the
- Best Effort umbrella, unless they are end-of-life. Releases past end-of-life are unlikely to work,
+ Best Effort umbrella, unless they are end-of-life. Releases past end-of-life are unlikely to work,
or may stop working with any future release.
The node releases schedule provides up-to-date information on the current status of all active
releases, and indicates the timelines for support (including planned End-of-Life dates for each).