Skip to content

README.md

Latest commit

 

History

History
137 lines (105 loc) · 8.55 KB

README.md

File metadata and controls

137 lines (105 loc) · 8.55 KB

Azure SDK for Java – Documentation Hub

This directory is the canonical documentation hub for the Azure SDK for Java repository. It is structured so that both humans and LLM/agent tooling can navigate directly to any topic.

Not sure where to start?

Repository at a Glance

Item Location
Root README (overview, packages, need help) /README.md
Contributing rules & PR process /CONTRIBUTING.md
Security policy /SECURITY.md
Support channels /SUPPORT.md
Code of Conduct /CODE_OF_CONDUCT.md
Per-library documentation sdk/<service>/<library>/README.md
Per-library changelog sdk/<service>/<library>/CHANGELOG.md
Engineering tooling & pipelines /eng/
GitHub Copilot agent instructions .github/copilot-instructions.md

Getting Started

The fastest way to start is to find your service in the list of available packages and follow that library's README.md.

All client libraries:

  • Baseline on Java 8 and are tested up to the latest Java LTS release.
  • Follow the Azure SDK Design Guidelines for Java.
  • Share common infrastructure (retry, logging, authentication, tracing) from azure-core.

Add whatever library you need. Example for Azure Blob Storage:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob</artifactId>
  <version>12.x.x</version>
</dependency>

Or use the Azure SDK BOM to manage versions automatically:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>1.2.x</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

See BOM Guidelines for details.

User Guides

For consumers of the Azure SDK for Java libraries:

Guide Description
Frequently Asked Questions Async gotchas, dependency conflicts, Security Manager
Azure Identity Examples All credential types with code samples
Configuration Environment variables, HTTP client tuning, retries
Logging SLF4J setup, log levels, HTTP logging, filtering by package
Performance Tuning SSL, connection pooling, async vs. sync
Test Proxy Migration Migrate test recordings to the external assets repo
Azure JSON Migration Replace Jackson with azure-json stream serialization
Serialization JacksonAdapter, JsonSerializer, default config
Protocol Methods Direct low-level HTTP access via RequestOptions
Management Libraries Auth, sync/async calls, LROs for ARM libraries
Azure V2 — Logging & HTTP clientcore logging best practices, OkHttp
Using the SDK with AI tools Copilot, MCP server, Azure SDK skills, AI coding tools

Contributor Guides

For developers building or maintaining SDK libraries:

Guide Description
Contributor Guide Index Index of all contributor guides
Getting Started Set up your dev environment (Java, Maven, Git, IDE)
Building Build commands, skipping analysis, HTML reports
Unit Testing Mocking, test parallelization, remote debugging
Live Testing Deploy test resources and run live tests
Code Quality CheckStyle, SpotBugs, Revapi, JaCoCo
Versioning Version files, dependency tags, incrementing
Adding a Module Create a new SDK module in the repo
TypeSpec Quickstart End-to-end workflow: generate, build, test, release
Working with AutoRest OpenAPI 2.0 / Swagger code generation
Writing Performance Tests perf-test-core benchmarking framework
JavaDoc & Code Snippets Javadoc standards + codesnippet plugin
Access Helpers Cross-package internal access without public APIs
Deprecation Process How to mark a library deprecated and release it
BOM Guidelines Azure SDK BOM (bill of materials) guidelines
Release Checklist Pre-release checklist from Beta 1 through GA
Credential Scan Monitor and fix CredScan warnings
SDK Generation Pipeline Troubleshooting Diagnose SDK auto-generation pipeline failures

Documentation Placement Decisions

See STRUCTURE.md for the full rationale on what lives here versus in eng/ or alongside individual SDK libraries.

Need Help?

Documentation

The docs/ directory is the authoritative source for contributor and user documentation. Key topics previously on the GitHub Wiki have been migrated here.
⚡