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

Add Documentation for MPG SDK generation #23837

Merged
merged 3 commits into from
Dec 18, 2024
Merged

Add Documentation for MPG SDK generation #23837

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cb67b65
Add Documentation fo r MPG SDK kgeneration
chidozieononiwu Dec 5, 2024
d0839ae
Make path os agnostic, remove extra white space
chidozieononiwu Dec 6, 2024
be0a17b
Remove stale sections
chidozieononiwu Dec 17, 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
67 changes: 67 additions & 0 deletions documentation/code-generation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,70 @@ generator –r –v –l=temp –version=v11.2.0-beta C:/azure-rest-api-specs/sp
## Generate Azure SDK for Go profiles
Copy link
Member

Choose a reason for hiding this comment

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

in terms of cleaning up the doc, @raych1 :

  • In which scenarios a service team will want to Generate Azure SDK for Go service packages in bulk ?
  • Because of how processes have changed, section Include a new package in the SDK should be removed too (this was added 7 years ago :| )

Copy link
Member

Choose a reason for hiding this comment

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

@tadelesh can you revisit the above instructions and update them accordingly if they are out of date?

Copy link
Member

Choose a reason for hiding this comment

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

i suggested to remove Generate Azure SDK for Go service packages in bulk, Include a new package in the SDK and Generate Azure SDK for Go profiles. they are all out of date. also, it seems Generate an Azure-SDK-for-Go service package is out of date, but needs @jhendrixMSFT to confirm.

Copy link
Member

Choose a reason for hiding this comment

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

Sorry I don't see this section in the diff. Is the name correct?

Copy link
Member Author

Choose a reason for hiding this comment

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

It's not part of the current diff https://github.com/Azure/azure-sdk-for-go/blob/main/documentation/code-generation.md#generate-an-azure-sdk-for-go-service-package

The question is whether it should be removed in this PR or not.

Copy link
Member

Choose a reason for hiding this comment

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

Got it. Yeah that's also out of date. Really it looks like that entire file needs to be rewritten.


Take a look into the [profile generator documentation](https://github.com/Azure/azure-sdk-for-go/tree/main/eng/tools/profileBuilder)

## Generate Go Mgmt SDK from Typespec
tadelesh marked this conversation as resolved.
Show resolved Hide resolved
### Prerequisites
- [Node.js 18.x LTS](https://nodejs.org/en/download) or later
- [Go 1.23.x](https://go.dev/doc/install) or later
- [Git](https://git-scm.com/downloads)
- Identify the `tspconfig.yaml` file for your package in the [Rest API Spec Repo](https://github.com/Azure/azure-rest-api-specs) and ensure there is a configuration for the Go SDK similar to that shown below and in [this example](https://github.com/Azure/azure-rest-api-specs/blob/b09c9ec927456021dc549e111fa2cac3b4b00659/specification/contosowidgetmanager/Contoso.Management/tspconfig.yaml#L40)
chidozieononiwu marked this conversation as resolved.
Show resolved Hide resolved

```yaml
options:
"@azure-tools/typespec-go":
service-dir: "SERVICE_DIRECTORY_NAME"
package-dir: "PACKAGE_DIRECTORY_NAME"
chidozieononiwu marked this conversation as resolved.
Show resolved Hide resolved
module: "github.com/Azure/azure-sdk-for-go/{service-dir}/{package-dir}"
fix-const-stuttering: true
flavor: "azure"
generate-examples: true
generate-fakes: true
head-as-boolean: true
inject-spans: true
remove-unreferenced-types: true
chidozieononiwu marked this conversation as resolved.
Show resolved Hide resolved
```
- Local Clone of Rest API Spec Repo Fork
- If you don't already have a fork, [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) the [Rest API Spec Repo](https://github.com/Azure/azure-rest-api-specs).
- Clone your fork of the repo.

```
git clone https://github.com/{YOUR_GITHUB_USERNAME}/azure-rest-api-specs.git
```
- Local Clone of Go Language Repo Fork
- If you don't already have a fork, [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) the [Go Repo](https://github.com/Azure/azure-sdk-for-go).
- Clone your fork of the repo.

```
git clone https://github.com/{YOUR_GITHUB_USERNAME}/azure-sdk-for-go.git
```

### Steps
1. Complete the prerequisites listed above
2. Run [automation_init.sh](https://github.com/Azure/azure-sdk-for-go/blob/main/eng/scripts/automation_init.sh)

```sh
cd "~/azure-sdk-for-go/eng/scripts" # navigate to the script directory
./automation_init.sh
```
> On windows you can use Git Bash to run the script. This script also installs the generator as a global tool.
3. Create a local json file named `generatedInput.json` with content similar to that shown below

```json
{
"dryRun": false,
"specFolder": "LOCAL_AZURE-REST-API-SPECS_REPO_ROOT", // e.g. "C:/git/azure-rest-api-specs"
"headSha": "SHA_OF_AZURE-REST-API-SPECS_REPO", // use ' git rev-parse HEAD ' on the local azure-rest-api-specs repo root
"repoHttpsUrl": "https://github.com/Azure/azure-rest-api-specs",
"relatedTypeSpecProjectFolder": [
"specification/SERVICE_DIRECTORY_NAME/PACKAGE_DIRECTORY_NAME/" // e.g specification/contosowidgetmanager/Contoso.Management
]
}
```
4. Run the [Generator](https://github.com/chidozieononiwu/azure-sdk-for-go/tree/main/eng/tools/generator)
```sh
generator automation-v2 "PATH_TO_generatedInput.json" generateOutput.json
```
> generateOutput.json is a parameter for the name of the output file that will be created by the script.

5. View information about the generated SDK in `generateOutput.json`
6. Prepare your SDK for release. The necessary approvals, guidance for testing, documentation, and release pipelines is described in your release plan. More information about the Azure SDK Release Tool is [here](https://eng.ms/docs/products/azure-developer-experience/plan/release-plan)
tadelesh marked this conversation as resolved.
Show resolved Hide resolved
Loading