Unverified Commit 7d1e3211 authored by John DiSanti's avatar John DiSanti Committed by GitHub
Browse files

Only output dev preview warning messages for 0.x versions (#3219) 

_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._
parent 17d3bdf2

aws/SDK_README.md.hb

+11 −4
Original line number Diff line number Diff line
@@ -5,6 +5,7 @@ It gets instantiated and copied into the build artifacts by the `aws:sdk:assembl 
Available template arguments:

- `{{sdk_version_<crate_name_in_snake_case>}}` (e.g., `{{sdk_version_aws_config}}` for the `aws-config` crate): the version number of the given crate (just the number, no `v` prefix)

- `{{msrv}}`: The MSRV Rust compiler version (just the number, no `v` prefix)

- `{{warning_banner}}`: Show the production warning banner

--}}

<!--

IMPORTANT:
@@ -14,11 +15,14 @@ To update it, edit the `aws/SDK_README.md.hb` Handlebars template in that reposi 


# The AWS SDK for Rust [![Docs](https://img.shields.io/badge/docs-blue)](https://awslabs.github.io/aws-sdk-rust/) ![MSRV](https://img.shields.io/badge/msrv-{{msrv}}-red) [![Usage Guide](https://img.shields.io/badge/Developer_Guide-blue)](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html)



This repo contains the new AWS SDK for Rust (the SDK) and its [public roadmap](https://github.com/orgs/awslabs/projects/50/views/1).

This repo contains the AWS SDK for Rust and its [public roadmap](https://github.com/orgs/awslabs/projects/50/views/1).



{{#if warning_banner}}

**Please Note**: The SDK is currently released as a developer preview, without support or assistance for use on production workloads. Any use in production is at your own risk.

{{/if}}



The SDK is code generated from [Smithy models](https://awslabs.github.io/smithy/) that represent each AWS service. The code used to generate the SDK can be found in [smithy-rs](https://github.com/smithy-lang/smithy-rs).

The SDK is code generated from [Smithy models](https://smithy.io/2.0/index.html) that represent each AWS service.

The code used to generate the SDK can be found in [smithy-rs](https://github.com/smithy-lang/smithy-rs).



## Getting Started with the SDK
@@ -67,7 +71,8 @@ In order to use the SDK, you must already have Rust and Cargo installed. If you 


## Using the SDK



While we're working on the SDK, detailed usage instructions will be added to the [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html). Please suggest additional sections for the guide by opening an issue and describing what you are trying to do.

Detailed usage instructions are available in the [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html).

Suggestions for additional sections or improvements for the guide are welcome. Please open an issue describing what you are trying to do.



## Getting Help

* [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html)
@@ -82,7 +87,9 @@ While we're working on the SDK, detailed usage instructions will be added to the 


The SDK uses **GitHub Issues** to track feature requests and issues with the SDK. In addition, we use **GitHub Projects** to provide users with a high level view of our roadmap and the features we're actively working on.



You can provide feedback or report a bug  by submitting a **GitHub issue**. This is the preferred mechanism to give feedback so that other users can engage in the conversation, +1 issues, etc. Issues you open will be evaluated for our roadmap in the Developer Preview launch.

You can provide feedback or report a bug  by submitting a **GitHub issue**.

This is the preferred mechanism to give feedback so that other users can engage in the conversation, +1 issues, etc.

Issues you open will be evaluated for our roadmap.



### Contributing

aws/rust-runtime/aws-config/README.md

+2 −3
Original line number Diff line number Diff line
@@ -2,8 +2,6 @@ 


AWS SDK config and credential provider implementations.



**Please Note: The SDK is currently released as an alpha and is intended strictly for feedback purposes only. Do not use this SDK for production workloads.**



 The implementations can be used either via the default chain implementation `from_env`/`ConfigLoader` or ad-hoc individual credential and region providers.



A `ConfigLoader` can combine different configuration sources into an AWS shared-config `Config`. The `Config` can then be used to configure one or more AWS service clients.
@@ -46,7 +44,8 @@ tokio = { version = "1", features = ["full"] } 


## Using the SDK



Until the SDK is released, we will be adding information about using the SDK to the [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html). Feel free to suggest additional sections for the guide by opening an issue and describing what you are trying to do.

Detailed usage instructions are available in the [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html).

Suggestions for additional sections or improvements for the guide are welcome. Please open an issue describing what you are trying to do.



## Getting Help

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/AwsCrateDocsDecorator.kt

+17 −9
Original line number Diff line number Diff line
@@ -103,12 +103,16 @@ internal class AwsCrateDocGenerator(private val codegenContext: ClientCodegenCon 
            else -> rawTemplate(text + "\n", *args)

        }



    private fun docText(

    internal fun docText(

        includeHeader: Boolean,

        includeLicense: Boolean,

        asComments: Boolean,

    ): Writable = writable {

        val moduleVersion = codegenContext.settings.moduleVersion

        check(moduleVersion.isNotEmpty() && moduleVersion[0].isDigit())



        val moduleName = codegenContext.settings.moduleName

        val stableVersion = !moduleVersion.startsWith("0.")

        val description = normalizeDescription(

            codegenContext.moduleName,

            codegenContext.settings.getService(codegenContext.model).getTrait<DocumentationTrait>()?.value ?: "",
@@ -119,7 +123,10 @@ internal class AwsCrateDocGenerator(private val codegenContext: ClientCodegenCon 
        if (includeHeader) {

            template(asComments, escape("# $moduleName\n"))

        }



        // TODO(PostGA): Remove warning banner conditionals.

        // NOTE: when you change this, you must also change SDK_README.md.hb

        if (!stableVersion) {

            template(

                asComments,

                """
@@ -127,6 +134,7 @@ internal class AwsCrateDocGenerator(private val codegenContext: ClientCodegenCon 
                on production workloads. Any use in production is at your own risk.**${"\n"}

                """.trimIndent(),

            )

        }



        if (description.isNotBlank()) {

            template(asComments, escape("$description\n"))
@@ -149,7 +157,7 @@ internal class AwsCrateDocGenerator(private val codegenContext: ClientCodegenCon 
            ```toml

            [dependencies]

            aws-config = { version = "$awsConfigVersion", features = ["behavior-version-latest"] }

            $moduleName = "${codegenContext.settings.moduleVersion}"

            $moduleName = "$moduleVersion"

            tokio = { version = "1", features = ["full"] }

            ```

aws/sdk-codegen/src/test/kotlin/AwsCrateDocsDecoratorTest.kt

+53 −0
Original line number Diff line number Diff line
@@ -4,10 +4,18 @@ 
 */



import org.junit.jupiter.api.Assertions.assertEquals

import org.junit.jupiter.api.Assertions.assertFalse

import org.junit.jupiter.api.Assertions.assertTrue

import org.junit.jupiter.api.Test

import software.amazon.smithy.model.loader.ModelAssembler

import software.amazon.smithy.model.node.ObjectNode

import software.amazon.smithy.model.shapes.ShapeId

import software.amazon.smithy.rust.codegen.client.testutil.testClientCodegenContext

import software.amazon.smithy.rust.codegen.client.testutil.testClientRustSettings

import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter

import software.amazon.smithy.rust.codegen.core.testutil.asSmithyModel

import software.amazon.smithy.rustsdk.AwsCrateDocGenerator

import software.amazon.smithy.rustsdk.AwsTestRuntimeConfig



class AwsCrateDocsDecoratorTest {

    private val codegenContext = testClientCodegenContext(ModelAssembler().assemble().unwrap())
@@ -106,4 +114,49 @@ class AwsCrateDocsDecoratorTest { 
            ),

        )

    }



    // TODO(PostGA): Remove warning banner conditionals.

    @Test

    fun warningBanner() {

        val context = { version: String ->

            testClientCodegenContext(

                model = """

                    namespace test



                    service Foobaz {

                    }

                """.asSmithyModel(),

                settings = testClientRustSettings(

                    moduleVersion = version,

                    service = ShapeId.from("test#Foobaz"),

                    runtimeConfig = AwsTestRuntimeConfig,

                    customizationConfig =

                    ObjectNode.parse(

                        """

                        { "awsSdk": {

                            "awsConfigVersion": "dontcare" } }

                        """,

                    ) as ObjectNode,

                ),

            )

        }



        // Test unstable versions first

        var codegenContext = context("0.36.0")

        var result = AwsCrateDocGenerator(codegenContext).docText(includeHeader = false, includeLicense = false, asComments = true).let { writable ->

            val writer = RustWriter.root()

            writable(writer)

            writer.toString()

        }

        assertTrue(result.contains("The SDK is currently released as a developer preview"))



        // And now stable versions

        codegenContext = context("1.0.0")

        result = AwsCrateDocGenerator(codegenContext).docText(includeHeader = false, includeLicense = false, asComments = true).let { writable ->

            val writer = RustWriter.root()

            writable(writer)

            writer.toString()

        }

        assertFalse(result.contains("The SDK is currently released as a developer preview"))

    }

}

aws/sdk-codegen/src/test/kotlin/SdkCodegenIntegrationTest.kt

+53 −0
Original line number Diff line number Diff line
@@ -4,7 +4,10 @@ 
 */



import org.junit.jupiter.api.Test

import software.amazon.smithy.rust.codegen.core.rustlang.rust

import software.amazon.smithy.rust.codegen.core.testutil.asSmithyModel

import software.amazon.smithy.rust.codegen.core.testutil.integrationTest

import software.amazon.smithy.rustsdk.awsIntegrationTestParams

import software.amazon.smithy.rustsdk.awsSdkIntegrationTest



class SdkCodegenIntegrationTest {
@@ -50,4 +53,54 @@ class SdkCodegenIntegrationTest { 
    fun smokeTestSdkCodegen() {

        awsSdkIntegrationTest(model) { _, _ -> /* it should compile */ }

    }



    // TODO(PostGA): Remove warning banner conditionals.

    @Test

    fun warningBanners() {

        // Unstable version

        awsSdkIntegrationTest(

            model,

            params = awsIntegrationTestParams().copy(moduleVersion = "0.36.0"),

        ) { _, rustCrate ->

            rustCrate.integrationTest("banner") {

                rust(

                    """

                    ##[test]

                    fn banner() {

                        use std::process::Command;

                        use std::path::Path;



                        // Verify we're in the right directory

                        assert!(Path::new("Cargo.toml").try_exists().unwrap());

                        let output = Command::new("grep").arg("developer preview").arg("-i").arg("-R").arg(".").output().unwrap();

                        assert_eq!(0, output.status.code().unwrap(), "it should output the banner");

                    }

                    """,

                )

            }

        }



        // Stable version

        awsSdkIntegrationTest(

            model,

            params = awsIntegrationTestParams().copy(moduleVersion = "1.0.0"),

        ) { _, rustCrate ->

            rustCrate.integrationTest("no_banner") {

                rust(

                    """

                    ##[test]

                    fn banner() {

                        use std::process::Command;

                        use std::path::Path;



                        // Verify we're in the right directory

                        assert!(Path::new("Cargo.toml").try_exists().unwrap());

                        let output = Command::new("grep").arg("developer preview").arg("-i").arg("-R").arg(".").output().unwrap();

                        assert_eq!(1, output.status.code().unwrap(), "it should _not_ output the banner");

                    }

                    """,

                )

            }

        }

    }

}