Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
237 lines (154 loc) · 15.4 KB

CONTRIBUTING.md

File metadata and controls

237 lines (154 loc) · 15.4 KB

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Where to begin

Core of the APIView tool is the web app developed using ASP.NET and TypeScript. This core module takes care of presenting reviews to users, storing review files and metadata in Azure Storage Account and Cosmos database and process requests from Azure Devops pipelines and respond. We also have language level parsers that converts each language specific artifact into a common json stub file that's known to core APIView web app. So, first step as a contributor is to understand the feature or bug fix you would like to submit and identify the area you would like to contribute to. Language parsers are either added as plugin modules developed in .NET or developed using corresponding language as command line tool to extract and generate stub file. If change is specific to a language in how langauge specific API details are extracted to stub tokens then change will be at parser level for that language. If change is applicable for all languages then change will most likely be in core APIView web app.

Module Source Path
apiview.dev https://github.com/Azure/azure-sdk-tools/tree/main/src/dotnet/APIView/APIViewWeb
C# https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIView/Languages/CodeFileBuilder.cs
C https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/Languages/CLanguageService.cs
C++ https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/Languages/CppLanguageService.cs
Java https://github.com/Azure/azure-sdk-tools/tree/main/src/java/apiview-java-processor
JS/TS https://github.com/Azure/azure-sdk-tools/tree/main/tools/apiview/parsers/js-api-parser
Python https://github.com/Azure/azure-sdk-tools/tree/main/packages/python-packages/apiview-stub-generator
Go https://github.com/Azure/azure-sdk-tools/tree/main/src/go
Rust https://github.com/Azure/azure-sdk-tools/tree/main/tools/apiview/parsers/rust-api-parser
Swift https://github.com/Azure/azure-sdk-tools/tree/main/src/swift

Pre-requisites

Development machine setup

Following are tools required to develop and run test instance of APIView to verify changes locally on your machine.

  • Git
  • Visual Studio
  • .NET
  • Any LTS version of Node.js download
  • Java (Optional: Only required if you want to generate Java review locally)
  • Python 3.9+ (Optional: Only required if you want to generate Python review locally)
  • Go compiler (Optional: Only to generate and test Go reviews)
  • Xcode 10.2 or higher (Optional: Only to generate and test Go reviews)
  • Azure subscription with permission to create storage account and Cosmos DB instance.

In addition to local machine setup, you will also require an Azure storage account to store source and stub file, an Azure App Configuration instance, and Azure Cosmos database instance to store review metadata. We have added a section below with more details on Azure resources required for testing.

Azure resources required to run APIView instance locally

You can verify your code changes locally by running a debugging instance of APIView tool locally using visual studio. This still requires Azure storage blob and Azure Cosmos DB instance to store stub file and metadata. Local development and testing do not require any Azure web app instance.

Create following Azure resources in your Azure subscription.

Azure storage account

  • Create a storage account in Azure. Azure storage account
  • Create three blob storage containers with names as follows within the storage account created in previous step: originals, codefiles, and usagesamples

Azure Cosmos DB

  • Create a Cosmos DB account in Azure and then create a database with name APIViewV2 in this account. Once database is created successfully then create three containers in APIViewV2 database. Following are the list of containers and partition key for each of them. Partition key is case sensitive.

    Container Name Partition Key
    Reviews /id
    APIRevisions /ReviewId
    Comments /ReviewId
    PullRequests /ReviewId
    SamplesRevisions /ReviewId
    Profiles /id
    APIVersions /ReviewId

Azure App Configuration

  • Create an Azure App Configuration instance in Azure. Azure App Configuration, it can be empty for basic local debugging.

Getting Started

Create a GitHub Oath application for local authentication

  • Go to github.com/<your GitHub username>
  • Go to Settings -> Developer Settings
  • Select OAuth Apps from menu options
  • Click on New OAuth App
  • Give an application name, for e.g. APIViewDebug and URL http://localhost:5000. Add same URL as call back URL also.
  • Copy Client ID and Secret for this OAuth app. These are required to be added in configuration to run local debugging instance.

Clone source code repo

  • Create a new fork of GitHub repo azure-sdk-tools
  • Clone forked repo to development machine.
  • Create a new branch from main branch of cloned source repo.

Setup debugging instance using Visual Studio

  • If you are making any changes to apiview core web app or any of the languages that are integrated within core web app (C, C++, C#) or to test APIVIew locally then open Visual Studio and load <azure-sdk-tools repo root/src/dotnet/APIView/APIView.sln

Connect local debugging instance to Azure resource

Following configuration is required to connect local debug instance to Azure resources as well as to setup debugging environment. Below are the steps to follow and required configuration to be added.

  • Right click on APIViewWeb project in APIView solution using solution explorer in Visual Studio and select Manage User Secrets.

  • Copy the following to secrets.json window opened using manage user secrets and update the configuration with valid GitHub OAuth client ID and secret and Cosmos and Storge connection string.

    { "Github": { "ClientId": "", "ClientSecret": "" }, "StorageAccountUrl": "https://.blob.core.windows.net/", "CosmosEndpoint": "Cosmos End point URL. For e.g. https://.documents.azure.com:443/", "CosmosDBName": "APIViewV2", "github-access-token": "", "ApiKey": "", "PYTHONEXECUTABLEPATH": "", "BackgroundTaskDisabled": true, "APPCONFIG_URL": "https://.azconfig.io" }

Note: User requires following role based access to storage account and cosmos DB for local debugging and make sure that user is logged in to Azure from Visual studio to access Azure resources.

  • Storage Blob Contributor to access storage account
  • Cosmos DB Built-in Data Contributor to access Cosmos DB

Role based access required for deployed instances

APIView Azure web app instance requires role based access to storage and cosmos DB instances to access using managed identity. Following are the required RBAC roles.

  • Storage Blob Contributor to access storage account
  • Cosmos DB Built-in Data Contributor to access Cosmos DB
  • App Configuration Data Reader to access App configuration.

Compile TypeScript code

APIView web app has some type script code and this needs to be compiled for client side processing. Following are the steps to compile typescript code before starting to debug APIView.

  • Go to <APIVIewWeb directory>/Client
  • run npm install
  • run npm run-script build

This should compile and get client-side scripting as well as CSS ready.

Verify setup

Okay. I have followed all the steps and now I need to verify if it's running fine locally to debug APIView. Download a NuGet file from NuGet package manager for any Azure package to test uploading to API review. One of the options is Azure.Template package here

  • Select APIViewWeb from solution explorer in Visual Studio and run debug or right click and select Debug -> Start New Instance

  • This should open a browser instance with login page to APIView. Click on the Login and this should ask your GitHub credentials and a confirmation to allow OAuth application created earlier to access your GitHub public information.

  • If GitHub Client ID configuration in manage user secrets is correct, login should be successful if you are part of Azure or Microsoft GitHub org and org information is publicly available under your GitHub account.

  • Home page should be displayed with an empty list of reviews.

  • Click Create Review button and upload previously downloaded Azure.Template package. It should show API review for Azure.Template if everything is setup correctly.

If any of the above steps is showing errors, following are the items to check:

  • Verify OAuth Client ID and Secret

  • Verify blob connection string and Cosmos DB connection string

  • Verify and ensure storage account has two containers as mentioned above

  • Verify and ensure cosmos DB instance has all 3 containers as per the instructions above and verify partition key for each of them.

SPA Client

APIView uses a SPA (Single Page Application) for part of its user interface. If adding completely new pages please make the contributions to the SPA client. See SPA Client Contributing Doc for more information.

Happy coding!!!!

I have made my changes. what's next?

If change is in core apiview web app module then start a debug run using Visual Studio and verify the change using an existing review as well as by creating a new review.

If change is specific to a language parser, then follow language specific parser testing guidelines.

C, C++, C#

  • Start Visual Studio debug run and create a new review as per the instructions in APIView README.md

Python

  • Install python api stub generator package using Python version configured in PYTHONEXECUTABLEPATH
  • Start Visual Studio debug run and create a new review as per the instructions in APIView README.md

Java

  • Build Java package parser jar file and copy the jar file to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/
  • Start Visual Studio debug run and create a new review as per the instructions in APIView README.md

Go

  • Compile and build Go source parser into .exe file and copy the .exe file to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/
  • Start Visual Studio debug run and create a new review as per the instructions in APIView README.md

JS/TS

  • Got to /tools/apiview/parsers/js-api-parser
  • run npm install
  • run npm run-script build
  • Copy compiled export.js to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/
  • Start Visual Studio debug run and create a new review as per the instructions in APIView README.md

Parser version should always be incremented if change is at parser level and if that change is required to be reflected on existing reviews as well. Existing reviews are refreshed to reflect the changes as a backend task if parser version is changed. So, this won't reflect immediately.

Create a GitHub pull request for the changes to merge it to main branch if code changes are ready and tested thoroughly.

Deployment to Production

Follow these steps to deploy to production:

  1. Approve the Prod Stage of the Build You Want to Deploy:

    • The APIView Pipeline runs automatically when changes are merged. Find the completed build you want to deploy and approve the Prod stage, which is the final deployment step awaiting approval.

  2. Wait for Pipeline Completion:

    • After the pipeline completes, the code will be deployed to the staging slot of the Azure Web App.

  3. Swap Deployment Slots:

    • The changes are now in the staging slot. To make them live in production:
      • Go to the APIView Web App.
      • Click on Swap.
      • Ensure the source is apiview-staging and the target is APIView.
      • Click Start swap to complete the process.

  4. Rollback (if needed):

    • In case of a regression and when there are no database changes, you can follow step 4 again to swap the deployment. This will restore the previous version.

Your deployment to production is now complete!
⚡