Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Component docs #4270

Merged
merged 4 commits into from
May 29, 2024
Merged

Update Component docs #4270

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9066618
Update Component docs
eerhardt May 23, 2024
eebf6e7
Update tests/Aspire.EndToEnd.Tests/README.md
eerhardt May 23, 2024
92b4be6
Update src/Components/README.md
eerhardt May 23, 2024
b0ae5bd
Update src/Components/README.md
eerhardt May 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions src/Components/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,25 @@ In summary we encourage and are excited to accept contributions of components, b

Each component is in its own NuGet package, and can version independently, including declaring itself in a preview state using the standard SemVer and NuGet mechanisms. However we expect the major and minor version of components to follow the core Aspire packages to make it easier to reason about dependencies. We expect to typically push updates to all components at the same time we update the core Aspire packages, but we have the ability to push an updated component at any other time if necessary, for example where changes to the underlying client library makes it necessary.

### Dependency Versioning

Applications usually have a direct reference to an Aspire component package (e.g `Aspire.StackExchange.Redis`) but have indirect references to the associated client libraries (e.g. `StackExchange.Redis`). This means that the version of the client libraries used by the application is derived from what the component package is built against.

Aspire component packages will be serviced monthly, capturing the latest available versions of the client libraries and Microsoft extensions they depend on, making it possible for applications built on Aspire to always benefit from the latest features and fixes.
eerhardt marked this conversation as resolved.
Show resolved Hide resolved

#### Breaking Changes

In the situation that a client library associated with an Aspire component package releases an update with a breaking change, the nature of the change will be assessed to determine its impact severity on the associated Aspire component package and Aspire applications that depend on it. If it’s decided that the change has high enough impact such that it would constitute a breaking change necessary to address, the Aspire component package will be split into 2 packages to support both versions.

To understand how this will work, an example of this is the `RabbitMQ.Client` library made many large breaking changes between version `6.8.1` and `7.0.0`. To handle this:

1. For the current `Aspire.RabbitMQ.Client` package, we put a NuGet version limit on our dependency: `[6.8.1,7.0.0)`. This way people won't be able to update to the `7.0.0` version, which will break their app.
2. When `RabbitMQ.Client` ships an official `7.0.0` stable package during the .NET Aspire `8.x` lifetime, we can add a new, forked component named `Aspire.RabbitMQ.Client.v7` which will have a dependency on `7.0.0` and contain any updates so the .NET Aspire component will work with v7. People who explicitly want to use v7 can opt into using this package.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tiny detail, but before there is a stable version, should we still create a version constraint? I'd probably suggest not to put a constraint until we have a package for the new version, since if we do it before, there will be an interim were an app that really needs to use the new preview version won't be able to with Aspire.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

before there is a stable version, should we still create a version constraint?

In my opinion, yes. This is the situation we are currently in with RabbitMQ. They currently have 7.0.0-alpha.6 on nuget. There isn't a stable 7.0.0 version yet. However, if someone tries to use our current Aspire component for RabbitMQ with the 7.0.0-alpha.6 version they will get a MissingMethodException (see #3956). Putting a version constraint on now signals to customers:

  1. The new, preview version is not expected to work
  2. We are aware of the problem.

3. When .NET Aspire 9 ships, we can "swap" the dependencies around.
- The `Aspire.RabbitMQ.Client` package will be updated to depend on v7 of `RabbitMQ.Client`.
- If `RabbitMQ.Client` v6 is still in support, we can create `Aspire.RabbitMQ.Client.v6` which has the dependency limit `[6.8.1, 7.0.0)` and works with the version 6 of RabbitMQ.Client.
- `Aspire.RabbitMQ.Client.v7` will be dead-ended. We won't make new .NET Aspire 9 versions of this package.

## Icon

Where the component represents some client technology that has a widely recognized logo, we would like to use that for the package icon if we can. Take a look at the MySql component for an example. We can only do this if the owner of the logo allows it - often you can find posted guidelines describing acceptable usage. Otherwise we can add reach out for explicit permission and do a follow up commit to add the icon if and when the use is approved.
Expand Down Expand Up @@ -201,6 +220,7 @@ New components MUST have:
* Public APIs
* Tests
* [ConformanceTests](../../tests/Aspire.Components.Common.Tests/ConformanceTests.cs)
* [EndToEndTests](../../tests/Aspire.EndToEnd.Tests/README.md#adding-tests-for-new-components)
* Other unit tests as needed
* Tracing support

Expand Down
14 changes: 14 additions & 0 deletions tests/Aspire.EndToEnd.Tests/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,20 @@
- set `<TestsRunningOutsideOfRepo>true</TestsRunningOutsideOfRepo>` to `tests/Aspire.EndToEnd.Tests/Directory.props` before any imports
- or set the environment variable `TestsRunningOutsideOfRepo=true`

## Adding tests for new components

The following changes need to be made to when adding a new component:

* Add a new `TestResourceNames` [enum entry](../testproject/Common/TestResourceNames.cs).
* Add ProjectReference to the new resource/component from the [TestProject.AppHost](../testproject/TestProject.AppHost/TestProject.AppHost.csproj) and [TestProject.IntegrationServiceA](../testproject/TestProject.IntegrationServiceA/TestProject.IntegrationServiceA.csproj) projects.
* Add PackageVersion entries to the new packages in [Directory.Packages.Helix.props](../testproject/Directory.Packages.Helix.props)
* Add entries to the Program.cs of both the AppHost and IntegrationServiceA projects.
* Add a test in [IntegrationServicesTests](../Aspire.EndToEnd.Tests/IntegrationServicesTests.cs)
* If the component's container starts in a reasonable time, the new test can just be a new `[InlineData]` entry to the existing `VerifyComponentWorks` test.
* If the container takes a long time to start, or is flaky, add a separate test scenario (similar to Oracle and Cosmos).

See https://github.com/dotnet/aspire/pull/4179 for an example.

## (details) What is the goal here?

1. We want to run some EndToEnd tests on CI, which can `dotnet run` an aspire project,
Expand Down