Skip to content

Wiki update: Steeltoe support policy #1

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

Open
bart-vmware wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Wiki update: Steeltoe support policy #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
51 changes: 23 additions & 28 deletions Home.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
* [Introduction](#introduction)
* [Overview](#overview)
* [Project Repositories](#project-repositories)
* [Releases](#releases)
* [Release Types](#release-types)
* [Getting Started](#getting-started)
* [Getting the Code](#getting-the-code)
* [Contributing](#contributing)
* [Governance Model](#governance-model)
* [Licenses](#licenses)
* [Licenses and Affiliations](#licenses-and-affiliations)

## Introduction
## Overview

Steeltoe is an open-source project aimed at developing cloud-native .NET microservice applications. This project provides libraries that follow similar development patterns from well-known and proven microservice libraries like Netflix OSS, Spring Cloud and others.
Steeltoe is an open-source project aimed at developing cloud-native .NET microservice applications. This project provides libraries that follow similar development patterns from well-known microservice libraries like Netflix OSS, Spring Cloud, and others.

Steeltoe libraries are built on top of .NET APIs.

Expand All @@ -21,31 +19,32 @@ Steeltoe libraries are built on top of .NET APIs.
Today, most Steeltoe components work in a stand-alone environment, as well as on cloud platforms (Kubernetes and Cloud Foundry).

Steeltoe components are built for .NET developers to quickly leverage some of the basic patterns typically found in highly scalable and resilient distributed applications.

Key features include:

* External (optionally encrypted) configuration using [Spring Cloud Config Server](https://docs.spring.io/spring-cloud-config/docs/current/reference/html/)
* Service discovery with [Netflix Eureka](https://spring.io/projects/spring-cloud-netflix) and [HashiCorp Consul](https://www.consul.io/)
* Management endpoints (compatible with [actuators](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html)), providing system info (such as versions, configuration, service container contents, mapped routes and HTTP traffic), heap/thread dumps, health checks, exporting metrics to [Prometheus](https://prometheus.io/), and changing log levels at runtime.
* Management endpoints (compatible with [actuators](https://docs.spring.io/spring-boot/reference/actuator/endpoints.html)), providing system info (such as versions, configuration, service container contents, mapped routes and HTTP traffic), heap/thread dumps, health checks, exporting metrics to [Prometheus](https://prometheus.io/), and changing log levels at runtime.
* Connectivity to databases (such as [SQL Server](https://www.microsoft.com/sql-server)/[Azure SQL](https://azure.microsoft.com/products/azure-sql), [Cosmos DB](https://azure.microsoft.com/products/cosmos-db/), [MongoDB](https://www.mongodb.com/), [Redis](https://redis.io/), [RabbitMQ](https://www.rabbitmq.com/), [PostgreSQL](https://www.postgresql.org/), and [MySQL](https://www.mysql.com/)), including support for [Entity Framework Core](https://learn.microsoft.com/ef/core/)
* Single sign-on, JWT and Certificate auth with [Cloud Foundry](https://www.cloudfoundry.org/)
* Single sign-on, JWT, and Certificate authentication with [Cloud Foundry](https://www.cloudfoundry.org/)

[Steeltoe is freely available](https://www.nuget.org/packages?q=Steeltoe) for production application usage today. Be sure to visit the [official Steeltoe site](https://steeltoe.io/).

## Project Repositories

Steeltoe is fully open-source and can be found under the [SteeltoeOSS organization on GitHub](https://github.com/SteeltoeOSS).
Steeltoe is open-source and can be found under the [SteeltoeOSS organization on GitHub](https://github.com/SteeltoeOSS).

### Steeltoe Core Components

These are located in the [Steeltoe](https://github.com/SteeltoeOSS/Steeltoe) repository:

* Configuration - configuration providers that extend the reach of .NET Configuration services
* Common - common packages used by other Steeltoe components
* Connectors - simplify the process of configuring and using back-end services locally and in the cloud
* Discovery - register and discover services locally and in the cloud
* Logging - view and change minimum log levels at runtime
* Common - shared packages used by other Steeltoe components
* Connectors - packages for configuring and connecting to backend services locally and in the cloud
* Discovery - service registration and discovery, locally and in the cloud
* Logging - dynamic log level management at runtime
* Management - monitoring and management endpoints for web applications
* Security - simplify integration of security services provided by the cloud platform
* Security - integration with cloud platform security services

### Other Repositories

Expand All @@ -64,11 +63,11 @@ These are located in the [Steeltoe](https://github.com/SteeltoeOSS/Steeltoe) rep
## Releases

Steeltoe releases are [listed](https://github.com/SteeltoeOSS/Steeltoe/releases) in the Steeltoe repository and are available on [NuGet.org](https://www.nuget.org/profiles/SteeltoeOSS).
For ongoing work, see the [issue milestones](https://github.com/SteeltoeOSS/Steeltoe/milestones) or [access pre-release packages](https://github.com/SteeltoeOSS/Steeltoe?tab=readme-ov-file#pre-release-packages).
For ongoing work, see the [issue milestones](https://github.com/SteeltoeOSS/Steeltoe/milestones) or the [pre-release packages](https://github.com/SteeltoeOSS/Steeltoe?tab=readme-ov-file#pre-release-packages).

### Release Types

* **Beta** (for example: beta1, beta2 ...)
* **Beta** (for example: beta1, beta2, ...)
A beta is a release that contains a subset of the full features planned for a release. Beta releases allow significant changes to be tested earlier in the release cycle. A beta release is not meant for production environments.
* **Release Candidate** (for example: rc1, rc2, ...)
A release candidate contains a full feature set and is available to the community for finding any last-minute major issues before the GA version is released. There could still be source code changes to fix defects, changes to documentation, and test cases, but these releases are generally considered production-grade and (until a GA release is available) their usage is supported in production environments.
Expand All @@ -83,11 +82,11 @@ For ongoing work, see the [issue milestones](https://github.com/SteeltoeOSS/Stee

## Contributing

The Steeltoe project welcomes contributions on GitHub both by filing issues and through PRs. You are also welcome to join our discussions on [Slack](https://slack.steeltoe.io/)
The Steeltoe project welcomes contributions on GitHub both by filing issues and through PRs. You are also welcome to join our [discussions on GitHub](https://github.com/SteeltoeOSS/Steeltoe/discussions).

Check out the [contributing guidelines](https://github.com/SteeltoeOSS/.github/blob/main/CONTRIBUTING.md) page to see how you can get involved and contribute to Steeltoe.

Also, its worth noting the Steeltoe project has adopted the code of conduct defined by the [Contributor Covenant](https://contributor-covenant.org/).
The Steeltoe project has adopted the code of conduct defined by the [Contributor Covenant](https://contributor-covenant.org/).
If you'd like more information, see the [.NET Foundation Code of Conduct](https://www.dotnetfoundation.org/code-of-conduct) write-up.

## Getting the Code
Expand All @@ -97,20 +96,16 @@ The development of the next Steeltoe version occurs in the `main` branch of the
The source code for released versions can be found by their [git tag](https://github.com/SteeltoeOSS/Steeltoe/tags).
For each released major version, a branch is available that contains the latest changes for that version. For example: `2.x`, `3.x`, `4.x`.

Similar branches exist in other repositories. For example, the `main` branch in [Samples](https://github.com/SteeltoeOSS/Samples) builds against the development NuGet feed, which is populated from the Steeltoe `main` branch. In contrast, its `2.x`, `3.x` and `4.x` branches build against the latest related Steeltoe version on nuget.org.
Similar branches exist in other repositories. For example, the `main` branch in [Samples](https://github.com/SteeltoeOSS/Samples) builds against the development NuGet feed, which is populated from the Steeltoe `main` branch. In contrast, its `2.x`, `3.x`, and `4.x` branches build against the latest related Steeltoe version on NuGet.org.

### Building from Source

Steeltoe components can be built from source with a recent version of the [.NET SDK](https://dotnet.microsoft.com/download/visual-studio-sdks) on Windows, Linux or macOS. Any IDE that supports .NET is expected to work. Core contributors regularly use Visual Studio, Visual Studio Code, and JetBrains Rider. Visual Studio Solution Filter (`.slnf`) files are provided for each component, along with a single `.slnx` file that contains all components.

### Running the tests

Running the integration tests requires Config Server and Eureka to be running. See [here](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md) for how to start them.
Steeltoe components can be built from source with a recent version of the [.NET SDK](https://dotnet.microsoft.com/download) on Windows, Linux, or macOS. Any IDE that supports .NET is expected to work. Core contributors regularly use Visual Studio, Visual Studio Code, and JetBrains Rider. Visual Studio Solution Filter (`.slnf`) files are provided for each component, along with a single `.slnx` file that contains all components.

## Governance Model
### Running the Tests

As a member of the [.NET Foundation](https://dotnetfoundation.org/), the Steeltoe project has adopted a [project governance](https://github.com/dotnet/home/blob/master/governance/project-governance.md) model in line with the recommendations made by the Foundation.
Comment thread
bart-vmware marked this conversation as resolved.
Running the integration tests requires Config Server and Eureka to be running. See the [CommonTasks guide](https://github.com/SteeltoeOSS/Samples/blob/main/CommonTasks.md) for how to start them.

## Licenses
## Licenses and Affiliations

The Steeltoe project uses the [Apache License Version 2.0](https://github.com/SteeltoeOSS/.github/blob/main/LICENSE.md) license for all of its code. See the [contribution licensing](https://github.com/SteeltoeOSS/.github/blob/main/contributing-docs/contributing-license.md) document for more details.
The Steeltoe project is a member of the [.NET Foundation](https://dotnetfoundation.org/) and is licensed under the [Apache License, Version 2.0](https://github.com/SteeltoeOSS/.github/blob/main/LICENSE.md). See the [contribution licensing](https://github.com/SteeltoeOSS/.github/blob/main/contributing-docs/contributing-license.md) document for more details.
34 changes: 18 additions & 16 deletions Release-Process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,36 @@

Due to breaking changes between release lines, portions of this document will not apply to release lines prior to `4.0.0`.

Please read the full contents of this page before taking action.
Read this page in full before taking action.

## Nuget package creation
> [!IMPORTANT]
> All deployments to NuGet.org require manual approval by a senior member of the Steeltoe team.

## NuGet package creation and publishing

All Steeltoe packages are produced by CI pipelines.
[This GitHub Actions workflow](https://github.com/SteeltoeOSS/Steeltoe/actions/workflows/package.yml) is used for building and releasing packages.

- Depending on how the workflow is triggered, packages may be signed, may deploy to the Steeltoe Azure Artifacts feed and may deploy to nuget.org.
- Depending on how the workflow is triggered, packages may be signed, deployed to the Steeltoe Azure Artifacts feed, and/or deployed to NuGet.org.

To build packages for nuget.org and trigger their release, [create a new GitHub release](https://github.com/SteeltoeOSS/Steeltoe/releases/new) with a tag that matches the `VersionPrefix` in [shared-package.props](https://github.com/SteeltoeOSS/Steeltoe/blob/main/shared-package.props).
The workflow will handle everything else. **All deployments to nuget.org require manual approval by a senior member of the Steeltoe team.**
To build packages for NuGet.org and trigger their release, [create a new GitHub release](https://github.com/SteeltoeOSS/Steeltoe/releases/new) with a tag that matches the `VersionPrefix` in [shared-package.props](https://github.com/SteeltoeOSS/Steeltoe/blob/main/shared-package.props).
The workflow will handle everything else.

## Release-time checklist

- Run `public-api-mark-shipped.ps1` to update `PublicAPI.*.txt` files.
- Ensure [schema.json](https://github.com/SteeltoeOSS/Schema) is up to date. If necessary, create a git tag and copy the latest schema to [Documentation](https://github.com/SteeltoeOSS/Documentation).
- Review [documentation](https://github.com/SteeltoeOSS/Documentation) and [samples](https://github.com/SteeltoeOSS/Samples) for references to `github.com/SteeltoeOSS/Steeltoe` and ensure all links point to the proper branches.
- If there are pending updates for documentation (https://steeltoe.io): use the [stage-prod-swap](https://github.com/SteeltoeOSS/Documentation/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
- If there are pending updates for NetCoreToolTemplates, [create a new GitHub release](https://github.com/SteeltoeOSS/NetCoreToolTemplates/releases/new) to build and release new template versions to nuget.org.
- **All deployments to nuget.org require manual approval by a senior member of the Steeltoe team.**
1. Run `public-api-mark-shipped.ps1` to update `PublicAPI.*.txt` files.
2. Ensure [schema.json](https://github.com/SteeltoeOSS/Schema) is up to date. If necessary, create a git tag and copy the latest schema to [Documentation](https://github.com/SteeltoeOSS/Documentation).
3. Review [documentation](https://github.com/SteeltoeOSS/Documentation) and [samples](https://github.com/SteeltoeOSS/Samples) for references to `github.com/SteeltoeOSS/Steeltoe` and ensure all links point to the proper branches.
4. If there are pending updates for the [documentation site](https://steeltoe.io): use the [stage-prod-swap](https://github.com/SteeltoeOSS/Documentation/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
5. If there are pending updates for NetCoreToolTemplates, [create a new GitHub release](https://github.com/SteeltoeOSS/NetCoreToolTemplates/releases/new) to build and release new template versions to NuGet.org.

> [!NOTE]
> Updates to NetCoreToolTemplates will not automatically be used by start.steeltoe.io. A new build of NetCoreToolService will always be required because templates are embedded within the container image.

- Consider updating settings at SteeltoeOSS/InitializrConfig
- If there are pending updates for NetCoreToolService: use the [stage-prod-swap](https://github.com/SteeltoeOSS/NetCoreToolService/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
- If there are pending updates for InitializrService: use the [stage-prod-swap](https://github.com/SteeltoeOSS/InitializrService/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
- If there are pending updates for InitializrWeb (https://start.steeltoe.io): use the [stage-prod-swap](https://github.com/SteeltoeOSS/InitializrWeb/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
6. If applicable, update settings in [InitializrConfig](https://github.com/SteeltoeOSS/InitializrConfig).
7. If there are pending updates for NetCoreToolService: use the [stage-prod-swap](https://github.com/SteeltoeOSS/NetCoreToolService/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
8. If there are pending updates for InitializrService: use the [stage-prod-swap](https://github.com/SteeltoeOSS/InitializrService/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.
9. If there are pending updates for [InitializrWeb](https://start.steeltoe.io): use the [stage-prod-swap](https://github.com/SteeltoeOSS/InitializrWeb/actions/workflows/stage-prod-swap.yml) action to swap the staging slot into production.

> [!TIP]
> For every case a "stage-prod-swap" workflow is run, consider using the corresponding "Build and stage xxx" to overwrite the retired production site (which was demoted to the corresponding staging slot) once the new version is confirmed as good to go.
> After each `stage-prod-swap` workflow run, consider using the corresponding `Build and stage` workflow to overwrite the retired production site (which was demoted to the staging slot) once the new version is confirmed stable.
Loading