Convert Python spec to Madoko, add it to the common output, remove the 'out' directory, and fix a CSS issue (#119)
This commit is contained in:
Jonathan Giles
GitHub
Родитель
f9ad5bfc02
Коммит
13b698b390
|
|
@ -328,3 +328,5 @@ ASALocalRun/
|
|||
|
||||
# MFractors (Xamarin productivity tool) working folder
|
||||
.mfractor/
|
||||
|
||||
out/
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Affiliation : ADP / .NET
|
|||
Email : kcwalina@microsoft.com
|
||||
Logo : False
|
||||
Embed : False
|
||||
css : ../custom.css
|
||||
css : custom.css
|
||||
|
||||
[INCLUDE=../components.mdk]
|
||||
|
||||
|
|
@ -426,6 +426,6 @@ allow any customer configuration or customization via a shared resource like a f
|
|||
|
||||
# Python Specific Guidelines
|
||||
|
||||
# JavaScript Specific Guidelines
|
||||
[INCLUDE=../python/DesignGuidelines.mdk]
|
||||
|
||||
# Go Specific Guidelines
|
||||
# JavaScript Specific Guidelines
|
||||
|
|
|
|||
|
|
@ -1,53 +0,0 @@
|
|||
body.madoko {
|
||||
font-size: 16px;
|
||||
font-family: Segoe UI, SegoeUI, Segoe WP, Helvetica Neue, Helvetica, Tahoma,
|
||||
Arial, sans-serif;
|
||||
}
|
||||
|
||||
.must,
|
||||
.mustnot,
|
||||
.should,
|
||||
.shouldnot,
|
||||
.may,
|
||||
.note,
|
||||
.todo,
|
||||
.example {
|
||||
position: relative;
|
||||
}
|
||||
|
||||
.todo {
|
||||
font-size: 80%;
|
||||
color: #666;
|
||||
}
|
||||
|
||||
.req-label {
|
||||
position: absolute;
|
||||
right: 100%;
|
||||
width: 100px;
|
||||
text-align: right;
|
||||
padding-right: 10px;
|
||||
}
|
||||
|
||||
a.req-label {
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.example {
|
||||
background-color: #eee;
|
||||
padding: 0 5px 5px 5px;
|
||||
}
|
||||
|
||||
:target {
|
||||
background-color: #ffff00a1;
|
||||
padding: 10px;
|
||||
border: black;
|
||||
border-width: 1px;
|
||||
border-style: dashed;
|
||||
}
|
||||
|
||||
.madoko code.code,
|
||||
.madoko span.code,
|
||||
.madoko pre code {
|
||||
color: #aa0000;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
|
@ -0,0 +1,489 @@
|
|||
## Supported Python versions {#python-scope; @h1-h2: decimal; }
|
||||
|
||||
~ Must {#python-version-support}
|
||||
provide packages supporting Python 2.7 and Python 3.4+
|
||||
~
|
||||
|
||||
## Supported Python interpreters
|
||||
|
||||
~ Must {#python-interpreters}
|
||||
consider supporting PyPy, Jython
|
||||
~
|
||||
|
||||
## Supported Operating systems
|
||||
|
||||
~ ToDo
|
||||
fill in
|
||||
~
|
||||
|
||||
## Coding
|
||||
### General
|
||||
|
||||
~ Must {#python-zen}
|
||||
adhere to the [Zen of Python](https://www.python.org/dev/peps/pep-0020/)
|
||||
|
||||
```
|
||||
Beautiful is better than ugly.
|
||||
Explicit is better than implicit.
|
||||
Simple is better than complex.
|
||||
Complex is better than complicated.
|
||||
Flat is better than nested.
|
||||
Sparse is better than dense.
|
||||
Readability counts.
|
||||
Special cases aren't special enough to break the rules.
|
||||
Although practicality beats purity.
|
||||
Errors should never pass silently.
|
||||
Unless explicitly silenced.
|
||||
In the face of ambiguity, refuse the temptation to guess.
|
||||
There should be one-- and preferably only one --obvious way to do it.
|
||||
Although that way may not be obvious at first unless you're Dutch.
|
||||
Now is better than never.
|
||||
Although never is often better than *right* now.
|
||||
If the implementation is hard to explain, it's a bad idea.
|
||||
If the implementation is easy to explain, it may be a good idea.
|
||||
Namespaces are one honking great idea -- let's do more of those!
|
||||
```
|
||||
~
|
||||
|
||||
~ Must {#python-guidelines}
|
||||
follow the general guidelines in [PEP8](https://www.python.org/dev/peps/pep-0008/t) unless explicitly overridden in this document.
|
||||
~
|
||||
|
||||
~ MustNot {#python-no-borrowing}
|
||||
"borrow" coding paradigms from other languages.
|
||||
|
||||
*For example, regardless of how common Reactive programming is in the Java community, it is still unfamiliar for most Python devalepers.*
|
||||
~
|
||||
|
||||
~ Must {#python-consistency}
|
||||
favor consistency with other Python components over other libraries for the same service
|
||||
|
||||
*It is significantly more likely that a developer will use many different libraries using the same languages than that a developer will use the same service from many different languages*
|
||||
~
|
||||
|
||||
~ Must {#python-single-underscore}
|
||||
use a single underscore to indicate that a name is not part of the public API and is not guaranteed stable.
|
||||
~
|
||||
|
||||
~ MustNot {#python-no-leading-underscore}
|
||||
use leading double underscore prefixed method names unless name clashes in inheritence hierarchy are likely. This is rare.
|
||||
~
|
||||
|
||||
~ Must {#python-structural-subtyping}
|
||||
prefer structural subtyping and protocols over explicit type checks
|
||||
|
||||
*It is [Easier to ask for forgiveness than permission](https://docs.python.org/3/glossary.html#term-eafp)*
|
||||
~
|
||||
|
||||
~ Must {#python-derive-appropriately}
|
||||
derive from the abstract collections base classes `collections.abc` (or `collections` for Python 2.7) when appropriate.
|
||||
~
|
||||
|
||||
~ Must {#python-type-hints}
|
||||
provide type hints [PEP484](https://www.python.org/dev/peps/pep-0484/) wherever you are providing class or function documentation.
|
||||
|
||||
- See the [suggested syntax for Python2.7 and straddling code](https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code) for guidance for Python 2.7 compatible code.
|
||||
~
|
||||
|
||||
### Naming
|
||||
|
||||
~ Must {#python-snake-case}
|
||||
use snake_case for variables and method names
|
||||
```python
|
||||
# Yes:
|
||||
service_client = ServiceClient()
|
||||
|
||||
# No:
|
||||
serviceClient = ServiceClient()
|
||||
```
|
||||
~
|
||||
|
||||
~ Must {#python-pascal-case}
|
||||
use Pascal case for Types
|
||||
|
||||
```python
|
||||
# Yes:
|
||||
class ThisIsCorrect(object):
|
||||
pass
|
||||
|
||||
|
||||
# No:
|
||||
class this_is_not_correct(object):
|
||||
pass
|
||||
|
||||
|
||||
# No:
|
||||
class camelCasedTypeName(object):
|
||||
pass
|
||||
```
|
||||
~
|
||||
|
||||
~ Must {#python-parameter-name}
|
||||
specify the parameter name when calling methods with more than two required positional parameters
|
||||
|
||||
```python
|
||||
def foo(a, b, c):
|
||||
pass
|
||||
|
||||
|
||||
def bar(d, e):
|
||||
pass
|
||||
|
||||
|
||||
# Yes:
|
||||
foo(a=1, b=2, c=3)
|
||||
bar(1, 2)
|
||||
bar(e=3, d=4)
|
||||
|
||||
# No:
|
||||
foo(1, 2, 3)
|
||||
```
|
||||
~
|
||||
|
||||
~ Must {#python-keyword-args}
|
||||
use keyword-only arguments for modules that only need to support Python 3.
|
||||
|
||||
```python
|
||||
# Yes
|
||||
def foo(a, *, b=1, c=None):
|
||||
...
|
||||
```
|
||||
~
|
||||
|
||||
~ Must {#python-parameter-name}
|
||||
specify the parameter name for optional parameters when calling functions
|
||||
|
||||
```python
|
||||
def foo(a, b=1, c=None):
|
||||
pass
|
||||
|
||||
|
||||
# Yes:
|
||||
foo(1, b=2, c=3)
|
||||
|
||||
# No:
|
||||
foo(1, 2, 3)
|
||||
```
|
||||
~
|
||||
|
||||
### Shared functionality
|
||||
|
||||
~ Must {#python-client-suffix}
|
||||
use the suffix "Client" for types accessing the service (Ex. CosmosClient)
|
||||
~
|
||||
|
||||
~ Must {#python-use-base-classes}
|
||||
use the base classes in [msrest](https://github.com/azure/msrest-for-python) whenever possible:
|
||||
|
||||
|Type|Usage|
|
||||
|-|-|
|
||||
|`msrest.SDKClient`|Service specific client.|
|
||||
|`msrest.configuration.Configuration`|Pass configuration information to `msres.SDKClient` derived classes.
|
||||
|`msrest.authentication.Authentication`|Make use an existing class of or derive from in order to provide support for additional authentication schemes.|
|
||||
|`msrest.serialization.Model`|Base class for models returned by service methods.
|
||||
|`msrest.paging.Paged`|Base class for return values for service methods that return lists of object. Also supports server driven paging|
|
||||
|`msrest.polling.PollingMethod`|Base class for return values for service methods that are long running.|
|
||||
~
|
||||
|
||||
~ Must {#python-pipeline-policies}
|
||||
provide pipeline policies for shared behavior
|
||||
~
|
||||
|
||||
~ Todo
|
||||
Provide common policies in previous statement
|
||||
~
|
||||
|
||||
### Common service patterns
|
||||
|
||||
~ Must {#python-auto-poll}
|
||||
provide a way to automatically poll on long running operations
|
||||
~
|
||||
|
||||
~ Must {#python-manual-poll}
|
||||
provide a way to manually poll on long running operations by returning an operations object
|
||||
|
||||
*A pattern of starting operation in process 1, handing off the info needed to poll to process 2 is a relatively common pattern in distributed computing.*
|
||||
~
|
||||
|
||||
~ Must {#python-pickled}
|
||||
make sure that operations objects can be [pickled](https://docs.python.org/3.7/library/pickle.html).
|
||||
~
|
||||
|
||||
~ Must {#python-crud-naming}
|
||||
prefer the use of the following terms for CRUD operations:
|
||||
|
||||
|Verb|Parameters|Returns|Comments|
|
||||
|-|-|-|-|
|
||||
| upsert_\<noun>|key, item|Updated or created item|Create new item or update existing item. |
|
||||
| create_\<noun>|key, item|Created item|Create new item. Fails if item already exists. |
|
||||
| update_\<noun>|key, partial item|Updated item|Fails if item does not exist. |
|
||||
| replace_\<noun>|key, item|Replace existing item|Completely replaces an existing item. Fails if the item does not exist. |
|
||||
| delete_\<noun>|key|None|Delete an existing item. Will succeed even if item did not exist. |
|
||||
| append_\<noun>|item|Appended item|Add item to a collection. Item will be added last. |
|
||||
| add_\<noun>|index, item|Added item|Add item to a collection. Item will be added last. |
|
||||
| remove_\<noun>|key|None or removed item|Remove item from a collection. |
|
||||
| get_\<noun>|key|Item|Will return None if item does not exist |
|
||||
| list_\<noun>||`msrest.Pageable[Item]`|Return list of items. Returns empty list if no items exist |
|
||||
| \<noun>\_exists|key|`bool`|Return True if the item exists. |
|
||||
~
|
||||
|
||||
~ Must {#python-long-op-naming}
|
||||
prefer the use of the following terms for long running operations:
|
||||
|
||||
- `begin_<verb>_<noun>` for methods returning an operation object
|
||||
~
|
||||
|
||||
~ Must {#python-iterators}
|
||||
provide iterators over paged results which handle subsequent calls transparently.
|
||||
|
||||
*`msrest.paging.Paged` is the preferred base class to provide this functionality.*
|
||||
~
|
||||
|
||||
### Namespaces
|
||||
|
||||
~ Must {#python-azure-namespace}
|
||||
add your code to the 'azure' namespace.
|
||||
~
|
||||
|
||||
~ Must {#python-aio-suffix}
|
||||
add use the .aio suffix to the namespace for clients.
|
||||
~
|
||||
|
||||
~ Todo
|
||||
[See packaging guidelines for more related guidance]
|
||||
~
|
||||
|
||||
### Exceptions
|
||||
|
||||
~ Must {#python-common-exceptions}
|
||||
provide a common exception base class deriving from:
|
||||
~
|
||||
|
||||
~ Todo
|
||||
common exception types for previous statement
|
||||
~
|
||||
|
||||
~ Must {#python-exceptions}
|
||||
prefer different derived exception types over only differentiating between types of errors using an exception code
|
||||
~
|
||||
|
||||
### Threads
|
||||
|
||||
~ Must {#python-thread-affinity}
|
||||
maintain thread affinity for user-provided code unless explicitly documented to not do so.
|
||||
~
|
||||
|
||||
~ ToDo
|
||||
We need to provide more specific guidance for the use of threads in SDKs. This includes scenarios with native callback libraries as well as parallell workloads.
|
||||
~
|
||||
|
||||
## Dependencies
|
||||
|
||||
~ Must {#python-dependencies}
|
||||
consider using the following packages for shared functionality:
|
||||
|
||||
- msrest
|
||||
- requests (synchronous HTTP)
|
||||
- aiohttp (asynchronous HTTP)
|
||||
~
|
||||
|
||||
~ Todo
|
||||
Fill in more dependencies above
|
||||
~
|
||||
|
||||
~ MustNot {#python-no-ext-deps}
|
||||
use external dependencies outside the list of "well known dependencies". To get a new dependency added, contact @adparch.
|
||||
~
|
||||
|
||||
~ Todo
|
||||
how to specify?
|
||||
~
|
||||
|
||||
~ MustNot {#python-no-vendor-deps}
|
||||
vendor dependencies unless approved by @adparch
|
||||
|
||||
*Vendoring dependencies in Python means including the source from another package as if it was part of your package*
|
||||
~
|
||||
|
||||
## Packaging
|
||||
|
||||
~ Must {#python-wheels}
|
||||
provide wheels for all supported Python versions and architectures
|
||||
~
|
||||
|
||||
~ Must {#python-publish-pypi}
|
||||
publish your packages to PyPI
|
||||
~
|
||||
|
||||
~ Must {#python-package-naming}
|
||||
name your package after the namespace of your main client class
|
||||
~
|
||||
|
||||
~ Must {#python-lowercase-packages}
|
||||
use all lowercase in your package name with a dash (-) as a separator.
|
||||
~
|
||||
|
||||
~ MustNot {#python-no-underscore-or-period}
|
||||
use underscore (_) or period (.) in your package name.
|
||||
~
|
||||
|
||||
~ Must {#python-semver}
|
||||
use semantic versioning for your package
|
||||
~
|
||||
|
||||
~ Must {#python-follow-packaging-guidance}
|
||||
follow the specific package guidance from packaging.md
|
||||
~
|
||||
|
||||
~ Todo
|
||||
Consolidate packaging wiki, python notes and this document
|
||||
~
|
||||
|
||||
~ Must {#python-use-pkgutil}
|
||||
use pkgutil style namespace packages
|
||||
~
|
||||
|
||||
~ Must {#python-use-azure-nspkg}
|
||||
depend on azure-nspkg for Python 2.x
|
||||
~
|
||||
|
||||
~ Must {#python-follow-pep420}
|
||||
follow PEP420 for Python 3.0
|
||||
~
|
||||
|
||||
~ Must {#python-include-init}
|
||||
include __init__.py for the namespace(s) in sdists
|
||||
~
|
||||
|
||||
### Binary extensions
|
||||
|
||||
~ Must {#python-support-operating-systems}
|
||||
support Windows, Linux (manylinux - see PEP513), macOS
|
||||
~
|
||||
|
||||
~ Must {#python-support-platforms}
|
||||
support x86, x64 and ARM
|
||||
~
|
||||
|
||||
~ Must {#python-support-unicode-ascii}
|
||||
support unicode and ascii versions of CPython
|
||||
~
|
||||
|
||||
## Async support
|
||||
|
||||
~ Must {#python-sync-and-async}
|
||||
consider providing both sync and async versions of your APIs
|
||||
~
|
||||
|
||||
~ Must {#python-use-async-await}
|
||||
use the async/await keywords (requires Python 3.5+)
|
||||
~
|
||||
|
||||
~ MustNot {#python-no-yield}
|
||||
use the [yield from coroutine/@asyncio.coroutine](https://docs.python.org/3.4/library/asyncio-task.html) syntax in order to support Python 3.4.
|
||||
~
|
||||
|
||||
~ Must {#python-async-package}
|
||||
consider shipping a separate package for async support if the async version requires additional dependencies.
|
||||
~
|
||||
|
||||
~ Must {#python-async-namespace}
|
||||
use the same namespace as the synchronous version of the package with .aio appended.
|
||||
~
|
||||
|
||||
~ Must {#python-async-naming}
|
||||
use the same name of the package as the synchronous version of the package with -aio appended.
|
||||
~
|
||||
|
||||
~ Must {#python-use-same-client-async}
|
||||
use the same client name for sync and async packages
|
||||
|
||||
Example:
|
||||
|
||||
|Sync/async|Namespace|Package name|Client name|
|
||||
|-|-|-|-|
|
||||
|Sync|azure.sampleservice|azure-sampleservice|azure.sampleservice.SampleServiceClient|
|
||||
|Async|azure.sampleservice.aio|azure-sampleservice-aio|azure.sampleservice.aio.SampleServiceClient|
|
||||
~
|
||||
|
||||
~ Must {#python-use-aiohttp}
|
||||
use aiohttp as the HTTP stack for async operations
|
||||
~
|
||||
|
||||
~ Must {#python-support-other-async}
|
||||
consider supporting async frameworks other than asyncio (i.e. Trio)
|
||||
~
|
||||
|
||||
## Testing
|
||||
|
||||
~ Must {#python-use-pytest}
|
||||
use pytest as the test framework
|
||||
~
|
||||
|
||||
~ Must {#python-use-pytest-asyncio}
|
||||
consider using pytest-asyncio for testing of async code.
|
||||
~
|
||||
|
||||
~ Must {#python-test-live-service}
|
||||
make your scenario tests runnable against live services
|
||||
~
|
||||
|
||||
~ Must {#python-test-recordings}
|
||||
provide recordings to allow running tests offline/without an Azure subscription
|
||||
~
|
||||
|
||||
~ Must {#python-simultanous-tests}
|
||||
support multiple simultanous test runs in the same subscription
|
||||
~
|
||||
|
||||
~ Must {#python-independent-tests}
|
||||
make each test case independent of other tests
|
||||
~
|
||||
|
||||
## Tooling
|
||||
|
||||
~ Must {#python-use-pylint}
|
||||
use pylint for your code.
|
||||
~
|
||||
|
||||
~ Todo
|
||||
Shared .pylintrc? Probably one per version of Python that is to be supported (e.g. unnescessary `object` inheritence should be avoided for Python3-only code, but is required for code straddling 2.7 and 3.x)
|
||||
~
|
||||
|
||||
~ Must {#python-use-flake8}
|
||||
use [flake8-docstrings](https://gitlab.com/pycqa/flake8-docstrings) to verify doccomments.
|
||||
~
|
||||
|
||||
~ Must {#python-use-black}
|
||||
use Black for formatting your code.
|
||||
~
|
||||
|
||||
~ Must {#python-use-mypy}
|
||||
consider using MyPy to statically check your code
|
||||
~
|
||||
|
||||
## Documenting your code
|
||||
|
||||
~ Must {#python-follow-pydocs}
|
||||
follow the guidelines in https://aka.ms/pydocs unless explicitly overridden in this document.
|
||||
~
|
||||
|
||||
~ Must {#python-docstring}
|
||||
use the Azure docstring guidelines to document your code
|
||||
~
|
||||
|
||||
~ Must {#python-code-snippets}
|
||||
provide code snippets for each non-trivial method
|
||||
~
|
||||
|
||||
~ Must {#python-document-exceptions}
|
||||
document exceptions that may be raised
|
||||
~
|
||||
|
||||
## Samples
|
||||
|
||||
~ Must {#python-samples}
|
||||
provide samples showing real-world usage of the package
|
||||
|
||||
- Error handling
|
||||
~
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
% Generated by Madoko, version 1.1.4
|
||||
%mdk-data-line={26}
|
||||
%mdk-data-line={421;./docs/design/common\../dotnet/DesignGuidelines.mdk:30}
|
||||
\citation{microsoft.com}
|
||||
%mdk-data-line={431}
|
||||
|
||||
%\cslstyle{madoko-numeric}
|
||||
%\csllocale{en-US}
|
||||
\bibdata{}
|
||||
%md5:d41d8cd98f00b204e9800998ecf8427e
|
||||
|
|
@ -1,739 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
|
||||
<meta name="generator" content="Madoko, version 1.1.4" />
|
||||
<meta name="viewport" content="initial-scale=1.0" />
|
||||
<meta name="author" content="Krzysztof Cwalina" />
|
||||
<title>Azure SDK Design Guidelines</title>
|
||||
<link rel="stylesheet" type="text/css" href="madoko.css" class="link">
|
||||
<link rel="stylesheet" type="text/css" href="../custom.css" class="link">
|
||||
|
||||
</head>
|
||||
<body class="madoko">
|
||||
|
||||
<div class="body madoko" style="line-adjust:0">
|
||||
<div class="titleblock align-center para-block" data-line="26" style="text-align:center;line-adjust:0">
|
||||
<div class="titleheader align-center" data-line="26" style="text-align:center;line-adjust:0">
|
||||
<div class="title para-block" data-line="26" style="font-size:xx-large;font-weight:bold;margin-bottom:0.5ex;line-adjust:0"><span data-line="26"></span>Azure SDK Design Guidelines</div>
|
||||
<div class="titlenote para-block" data-line="29" style="line-adjust:0"><span data-line="29"></span>Version 1.0.0-preview2</div></div>
|
||||
<div class="authors align-center" data-line="34" style="text-align:center;width:80%;line-adjust:0"><table class="authorrow columns block" data-line="34" style="margin-top:2ex;width:100%;line-adjust:0">
|
||||
<tbody><tr><td class="author column" data-line="34" style="text-align:center;line-adjust:0">
|
||||
<div class="authorname" data-line="34" style="font-size:large;line-adjust:0"><span data-line="34"></span>Brian Terlson</div>
|
||||
<div class="authoraddress" data-line="37" style="line-adjust:0"><span data-line="37"></span>ADP / JS & TS</div>
|
||||
<div class="authoremail email" data-line="40" style="line-adjust:0"><span data-line="40"></span>brian.terlson@microsoft.com</div></td><td class="author column" data-line="45" style="text-align:center;line-adjust:0">
|
||||
<div class="authorname" data-line="45" style="font-size:large;line-adjust:0"><span data-line="45"></span>Jeffrey Richter</div>
|
||||
<div class="authoraddress" data-line="48" style="line-adjust:0"><span data-line="48"></span>ADP / .NET</div>
|
||||
<div class="authoremail email" data-line="51" style="line-adjust:0"><span data-line="51"></span>jeffreyr@microsoft.com</div></td><td class="author column" data-line="56" style="text-align:center;line-adjust:0">
|
||||
<div class="authorname" data-line="56" style="font-size:large;line-adjust:0"><span data-line="56"></span>Johan Stenberg</div>
|
||||
<div class="authoraddress" data-line="59" style="line-adjust:0"><span data-line="59"></span>ADP / Python</div>
|
||||
<div class="authoremail email" data-line="62" style="line-adjust:0"><span data-line="62"></span>johan.stenberg@microsoft.com</div></td></tr></tbody></table><table class="authorrow columns block" data-line="69" style="margin-top:2ex;width:100%;line-adjust:0">
|
||||
<tbody><tr><td class="author column" data-line="69" style="text-align:center;line-adjust:0">
|
||||
<div class="authorname" data-line="69" style="font-size:large;line-adjust:0"><span data-line="69"></span>Jonathan Giles</div>
|
||||
<div class="authoraddress" data-line="72" style="line-adjust:0"><span data-line="72"></span>ADP / Java</div>
|
||||
<div class="authoremail email" data-line="75" style="line-adjust:0"><span data-line="75"></span>jonathan.giles@microsoft.com</div></td><td class="author column" data-line="80" style="text-align:center;line-adjust:0">
|
||||
<div class="authorname" data-line="80" style="font-size:large;line-adjust:0"><span data-line="80"></span>Krzysztof Cwalina</div>
|
||||
<div class="authoraddress" data-line="83" style="line-adjust:0"><span data-line="83"></span>ADP / .NET</div>
|
||||
<div class="authoremail email" data-line="86" style="line-adjust:0"><span data-line="86"></span>kcwalina@microsoft.com</div></td></tr></tbody></table></div></div>
|
||||
<p class="p noindent para-continued" data-line="29"><span data-line="29"></span>This document describes architectural and API design guidelines for Azure dataplane client libraries. These guidelines apply to all programming languages.
|
||||
There are also language-specific guidelines for C<span data-line="30"></span>#<span data-line="30"></span>, Java, Python, and JavaScript. If any language-specific guideline conflicts with anything in this guideline,
|
||||
the language-specific guideline should be followed.
|
||||
</p><span data-line="33"></span>
|
||||
<nav class="toc toc-contents"><h2 id="sec-contents" class="clearnum h1 heading-contents" data-heading-depth="1" style="display:block">Contents</h2>
|
||||
<div class="tocblock tocblock1">
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-terminology" data-toc-depth="1" data-toc-line="[1]{.heading-label}. Terminology" style="toctarget:sec-terminology"><a href="#sec-terminology" class="localref"><span class="heading-label">1</span>. Terminology</a></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-pre-requisites" data-toc-depth="1" data-toc-line="[2]{.heading-label}. Pre-requisites" style="toctarget:sec-pre-requisites"><a href="#sec-pre-requisites" class="localref"><span class="heading-label">2</span>. Pre-requisites</a></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-functionality" data-toc-depth="1" data-toc-line="[3]{.heading-label}. Functionality" style="toctarget:sec-functionality"><a href="#sec-functionality" class="localref"><span class="heading-label">3</span>. Functionality</a></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-operating-systems" data-toc-depth="1" data-toc-line="[4]{.heading-label}. Operating Systems" style="toctarget:sec-operating-systems"><a href="#sec-operating-systems" class="localref"><span class="heading-label">4</span>. Operating Systems</a></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-github-requirements" data-toc-depth="1" data-toc-line="[5]{.heading-label}. GitHub Requirements" style="toctarget:sec-github-requirements"><a href="#sec-github-requirements" class="localref"><span class="heading-label">5</span>. GitHub Requirements</a></div>
|
||||
<div class="tocblock tocblock2">
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-readmespanspanmd" data-toc-depth="2" data-toc-line="[5.1]{.heading-label}. README<span></span>.md" style="toctarget:sec-readmespanspanmd"><a href="#sec-readmespanspanmd" class="localref"><span class="heading-label">5.1</span>. README<span></span>.md</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-contributingspanspanmd" data-toc-depth="2" data-toc-line="[5.2]{.heading-label}. CONTRIBUTING<span></span>.md" style="toctarget:sec-contributingspanspanmd"><a href="#sec-contributingspanspanmd" class="localref"><span class="heading-label">5.2</span>. CONTRIBUTING<span></span>.md</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-licensespanspanmd" data-toc-depth="2" data-toc-line="[5.3]{.heading-label}. LICENSE<span></span>.md" style="toctarget:sec-licensespanspanmd"><a href="#sec-licensespanspanmd" class="localref"><span class="heading-label">5.3</span>. LICENSE<span></span>.md</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-codeowners" data-toc-depth="2" data-toc-line="[5.4]{.heading-label}. CODEOWNERS" style="toctarget:sec-codeowners"><a href="#sec-codeowners" class="localref"><span class="heading-label">5.4</span>. CODEOWNERS</a></div></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-language-specific-guidelines" data-toc-depth="1" data-toc-line="[6]{.heading-label}. Language-Specific Guidelines" style="toctarget:sec-language-specific-guidelines"><a href="#sec-language-specific-guidelines" class="localref"><span class="heading-label">6</span>. Language-Specific Guidelines</a></div>
|
||||
<div class="tocblock tocblock2">
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="common-general" data-toc-depth="2" data-toc-line="[6.1]{.heading-label}. General Guidelines" style="toctarget:common-general"><a href="#common-general" class="localref"><span class="heading-label">6.1</span>. General Guidelines</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="general-telemetry" data-toc-depth="2" data-toc-line="[6.2]{.heading-label}. Telemetry" style="toctarget:general-telemetry"><a href="#general-telemetry" class="localref"><span class="heading-label">6.2</span>. Telemetry</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="general-logging" data-toc-depth="2" data-toc-line="[6.3]{.heading-label}. Logging" style="toctarget:general-logging"><a href="#general-logging" class="localref"><span class="heading-label">6.3</span>. Logging</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="general-retry" data-toc-depth="2" data-toc-line="[6.4]{.heading-label}. Retry" style="toctarget:general-retry"><a href="#general-retry" class="localref"><span class="heading-label">6.4</span>. Retry</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-cancellation-timeouts" data-toc-depth="2" data-toc-line="[6.5]{.heading-label}. Cancellation & Timeouts" style="toctarget:sec-cancellation-timeouts"><a href="#sec-cancellation-timeouts" class="localref"><span class="heading-label">6.5</span>. Cancellation & Timeouts</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-dependencies" data-toc-depth="2" data-toc-line="[6.6]{.heading-label}. Dependencies" style="toctarget:sec-dependencies"><a href="#sec-dependencies" class="localref"><span class="heading-label">6.6</span>. Dependencies</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-configuration" data-toc-depth="2" data-toc-line="[6.7]{.heading-label}. Configuration" style="toctarget:sec-configuration"><a href="#sec-configuration" class="localref"><span class="heading-label">6.7</span>. Configuration</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-other-topics-to-be-covered" data-toc-depth="2" data-toc-line="[6.8]{.heading-label}. Other topics to be covered" style="toctarget:sec-other-topics-to-be-covered"><a href="#sec-other-topics-to-be-covered" class="localref"><span class="heading-label">6.8</span>. Other topics to be covered</a></div></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-c-specific-guidelines" data-toc-depth="1" data-toc-line="[7]{.heading-label}. C# Specific Guidelines" style="toctarget:sec-c-specific-guidelines"><a href="#sec-c-specific-guidelines" class="localref"><span class="heading-label">7</span>. C# Specific Guidelines</a></div>
|
||||
<div class="tocblock tocblock2">
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-general-net-api-design" data-toc-depth="2" data-toc-line="[7.1]{.heading-label}. General .NET API Design" style="toctarget:sec-general-net-api-design"><a href="#sec-general-net-api-design" class="localref"><span class="heading-label">7.1</span>. General .NET API Design</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-basic-azure-sdk-design-pattern" data-toc-depth="2" data-toc-line="[7.2]{.heading-label}. Basic Azure SDK Design Pattern" style="toctarget:sec-basic-azure-sdk-design-pattern"><a href="#sec-basic-azure-sdk-design-pattern" class="localref"><span class="heading-label">7.2</span>. Basic Azure SDK Design Pattern</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-naming-gudelines" data-toc-depth="2" data-toc-line="[7.3]{.heading-label}. Naming Gudelines" style="toctarget:sec-naming-gudelines"><a href="#sec-naming-gudelines" class="localref"><span class="heading-label">7.3</span>. Naming Gudelines</a></div>
|
||||
<div class="tocblock tocblock3">
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-namespace-naming" data-toc-depth="3" data-toc-line="[7.3.1]{.heading-label}. Namespace Naming" style="toctarget:sec-namespace-naming"><a href="#sec-namespace-naming" class="localref"><span class="heading-label">7.3.1</span>. Namespace Naming</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-type-naming" data-toc-depth="3" data-toc-line="[7.3.2]{.heading-label}. Type Naming" style="toctarget:sec-type-naming"><a href="#sec-type-naming" class="localref"><span class="heading-label">7.3.2</span>. Type Naming</a></div></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-packaging-and-versioning" data-toc-depth="2" data-toc-line="[7.4]{.heading-label}. Packaging and Versioning" style="toctarget:sec-packaging-and-versioning"><a href="#sec-packaging-and-versioning" class="localref"><span class="heading-label">7.4</span>. Packaging and Versioning</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-error-reporting" data-toc-depth="2" data-toc-line="[7.5]{.heading-label}. Error Reporting" style="toctarget:sec-error-reporting"><a href="#sec-error-reporting" class="localref"><span class="heading-label">7.5</span>. Error Reporting</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-authentication" data-toc-depth="2" data-toc-line="[7.6]{.heading-label}. Authentication" style="toctarget:sec-authentication"><a href="#sec-authentication" class="localref"><span class="heading-label">7.6</span>. Authentication</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-repository-guidelines" data-toc-depth="2" data-toc-line="[7.7]{.heading-label}. Repository Guidelines" style="toctarget:sec-repository-guidelines"><a href="#sec-repository-guidelines" class="localref"><span class="heading-label">7.7</span>. Repository Guidelines</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-common-type-usage" data-toc-depth="2" data-toc-line="[7.8]{.heading-label}. Common Type Usage" style="toctarget:sec-common-type-usage"><a href="#sec-common-type-usage" class="localref"><span class="heading-label">7.8</span>. Common Type Usage</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-commonly-overlooked-net-api-design-guidelines" data-toc-depth="2" data-toc-line="[7.A]{.heading-label}. Commonly Overlooked .NET API Design Guidelines" style="toctarget:sec-commonly-overlooked-net-api-design-guidelines"><a href="#sec-commonly-overlooked-net-api-design-guidelines" class="localref"><span class="heading-label">7.A</span>. Commonly Overlooked .NET API Design Guidelines</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-azure-http-pipeline" data-toc-depth="2" data-toc-line="[7.B]{.heading-label}. Azure Http Pipeline" style="toctarget:sec-azure-http-pipeline"><a href="#sec-azure-http-pipeline" class="localref"><span class="heading-label">7.B</span>. Azure Http Pipeline</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-appendix-z--todo" data-toc-depth="2" data-toc-line="[7.C]{.heading-label}. Appendix Z: TODO" style="toctarget:sec-appendix-z--todo"><a href="#sec-appendix-z--todo" class="localref"><span class="heading-label">7.C</span>. Appendix Z: TODO</a></div></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-java-specific-guidelines" data-toc-depth="1" data-toc-line="[8]{.heading-label}. Java Specific Guidelines" style="toctarget:sec-java-specific-guidelines"><a href="#sec-java-specific-guidelines" class="localref"><span class="heading-label">8</span>. Java Specific Guidelines</a></div>
|
||||
<div class="tocblock tocblock2">
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="java-scope" data-toc-depth="2" data-toc-line="[8.1]{.heading-label}. Scope" style="toctarget:java-scope"><a href="#java-scope" class="localref"><span class="heading-label">8.1</span>. Scope</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-platform-support" data-toc-depth="2" data-toc-line="[8.2]{.heading-label}. Platform Support" style="toctarget:sec-platform-support"><a href="#sec-platform-support" class="localref"><span class="heading-label">8.2</span>. Platform Support</a></div>
|
||||
<div class="tocblock tocblock3">
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-operating-systems" data-toc-depth="3" data-toc-line="[8.2.1]{.heading-label}. Operating Systems" style="toctarget:sec-operating-systems"><a href="#sec-operating-systems" class="localref"><span class="heading-label">8.2.1</span>. Operating Systems</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-supported-java-versions" data-toc-depth="3" data-toc-line="[8.2.2]{.heading-label}. Supported Java Versions" style="toctarget:sec-supported-java-versions"><a href="#sec-supported-java-versions" class="localref"><span class="heading-label">8.2.2</span>. Supported Java Versions</a></div></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-versioning" data-toc-depth="2" data-toc-line="[8.3]{.heading-label}. Versioning" style="toctarget:sec-versioning"><a href="#sec-versioning" class="localref"><span class="heading-label">8.3</span>. Versioning</a></div>
|
||||
<div class="tocblock tocblock3">
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-beta-api" data-toc-depth="3" data-toc-line="[8.3.1]{.heading-label}. Beta API" style="toctarget:sec-beta-api"><a href="#sec-beta-api" class="localref"><span class="heading-label">8.3.1</span>. Beta API</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-snapshot-releases" data-toc-depth="3" data-toc-line="[8.3.2]{.heading-label}. Snapshot Releases" style="toctarget:sec-snapshot-releases"><a href="#sec-snapshot-releases" class="localref"><span class="heading-label">8.3.2</span>. Snapshot Releases</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-preview-releases" data-toc-depth="3" data-toc-line="[8.3.3]{.heading-label}. Preview Releases" style="toctarget:sec-preview-releases"><a href="#sec-preview-releases" class="localref"><span class="heading-label">8.3.3</span>. Preview Releases</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-ga-releases" data-toc-depth="3" data-toc-line="[8.3.4]{.heading-label}. GA Releases" style="toctarget:sec-ga-releases"><a href="#sec-ga-releases" class="localref"><span class="heading-label">8.3.4</span>. GA Releases</a></div></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-naming" data-toc-depth="2" data-toc-line="[8.4]{.heading-label}. Naming" style="toctarget:sec-naming"><a href="#sec-naming" class="localref"><span class="heading-label">8.4</span>. Naming</a></div>
|
||||
<div class="tocblock tocblock3">
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-determing-group-and-service-name" data-toc-depth="3" data-toc-line="[8.4.1]{.heading-label}. Determing Group and Service Name" style="toctarget:sec-determing-group-and-service-name"><a href="#sec-determing-group-and-service-name" class="localref"><span class="heading-label">8.4.1</span>. Determing Group and Service Name</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-java-package-naming" data-toc-depth="3" data-toc-line="[8.4.2]{.heading-label}. Java Package Naming" style="toctarget:sec-java-package-naming"><a href="#sec-java-package-naming" class="localref"><span class="heading-label">8.4.2</span>. Java Package Naming</a></div></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-maven" data-toc-depth="2" data-toc-line="[8.5]{.heading-label}. Maven" style="toctarget:sec-maven"><a href="#sec-maven" class="localref"><span class="heading-label">8.5</span>. Maven</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-dependencies" data-toc-depth="2" data-toc-line="[8.6]{.heading-label}. Dependencies" style="toctarget:sec-dependencies"><a href="#sec-dependencies" class="localref"><span class="heading-label">8.6</span>. Dependencies</a></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-coding-conventions" data-toc-depth="2" data-toc-line="[8.7]{.heading-label}. Coding Conventions" style="toctarget:sec-coding-conventions"><a href="#sec-coding-conventions" class="localref"><span class="heading-label">8.7</span>. Coding Conventions</a></div>
|
||||
<div class="tocblock tocblock3">
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-async" data-toc-depth="3" data-toc-line="[8.7.1]{.heading-label}. Async" style="toctarget:sec-async"><a href="#sec-async" class="localref"><span class="heading-label">8.7.1</span>. Async</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-pipelines" data-toc-depth="3" data-toc-line="[8.7.2]{.heading-label}. Pipelines" style="toctarget:sec-pipelines"><a href="#sec-pipelines" class="localref"><span class="heading-label">8.7.2</span>. Pipelines</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-logging" data-toc-depth="3" data-toc-line="[8.7.3]{.heading-label}. Logging" style="toctarget:sec-logging"><a href="#sec-logging" class="localref"><span class="heading-label">8.7.3</span>. Logging</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-tooling" data-toc-depth="3" data-toc-line="[8.7.4]{.heading-label}. Tooling" style="toctarget:sec-tooling"><a href="#sec-tooling" class="localref"><span class="heading-label">8.7.4</span>. Tooling</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-testing" data-toc-depth="3" data-toc-line="[8.7.5]{.heading-label}. Testing" style="toctarget:sec-testing"><a href="#sec-testing" class="localref"><span class="heading-label">8.7.5</span>. Testing</a></div></div>
|
||||
<div class="tocitem tocitem2" data-toc-target-elem="h2" data-toc-target="sec-documentation" data-toc-depth="2" data-toc-line="[8.8]{.heading-label}. Documentation" style="toctarget:sec-documentation"><a href="#sec-documentation" class="localref"><span class="heading-label">8.8</span>. Documentation</a></div>
|
||||
<div class="tocblock tocblock3">
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-code-samples" data-toc-depth="3" data-toc-line="[8.8.1]{.heading-label}. Code Samples" style="toctarget:sec-code-samples"><a href="#sec-code-samples" class="localref"><span class="heading-label">8.8.1</span>. Code Samples</a></div>
|
||||
<div class="tocitem tocitem3" data-toc-target-elem="h3" data-toc-target="sec-javadoc" data-toc-depth="3" data-toc-line="[8.8.2]{.heading-label}. JavaDoc" style="toctarget:sec-javadoc"><a href="#sec-javadoc" class="localref"><span class="heading-label">8.8.2</span>. JavaDoc</a></div></div></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-python-specific-guidelines" data-toc-depth="1" data-toc-line="[9]{.heading-label}. Python Specific Guidelines" style="toctarget:sec-python-specific-guidelines"><a href="#sec-python-specific-guidelines" class="localref"><span class="heading-label">9</span>. Python Specific Guidelines</a></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-javascript-specific-guidelines" data-toc-depth="1" data-toc-line="[10]{.heading-label}. JavaScript Specific Guidelines" style="toctarget:sec-javascript-specific-guidelines"><a href="#sec-javascript-specific-guidelines" class="localref"><span class="heading-label">10</span>. JavaScript Specific Guidelines</a></div>
|
||||
<div class="tocitem tocitem1" data-toc-target-elem="h1" data-toc-target="sec-go-specific-guidelines" data-toc-depth="1" data-toc-line="[11]{.heading-label}. Go Specific Guidelines" style="toctarget:sec-go-specific-guidelines"><a href="#sec-go-specific-guidelines" class="localref"><span class="heading-label">11</span>. Go Specific Guidelines</a></div></div></nav><h2 id="sec-terminology" class="h1" data-line="35" data-heading-depth="1" style="display:block"><span data-line="35"></span><span class="heading-before"><span class="heading-label">1</span>. </span><span data-line="35"></span>Terminology</h2>
|
||||
<ul class="ul list-dash loose" data-line="37">
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="37">
|
||||
<p data-line="37"><span data-line="37"></span><strong class="strong-star2">SDK</strong><span data-line="37"></span>: Software Development Kit. This refers to the entire Azure SDK for a single language, itself broken up into numerous Azure SDK Components (as defined below).
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="39">
|
||||
<p data-line="39"><span data-line="39"></span><strong class="strong-star2">Azure SDK Component</strong><span data-line="39"></span>: An Azure SDK component (also referred to as <span data-line="39"></span>‘SDK component’<span data-line="39"></span>, or simply <span data-line="39"></span>‘component’<span data-line="39"></span>) represents the software (and associated tools, documentation, samples, etc.) that
|
||||
exist to support a single Azure service. Each Azure SDK component is published separately to the appropriate language-specific locations. These releases are performed exclusively by the Azure SDK
|
||||
engineering systems team. Developers consume and use each component separately as necessary to solve their use case.
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="43">
|
||||
<p data-line="43"><span data-line="43"></span><strong class="strong-star2">Client Library</strong><span data-line="43"></span>. This refers to a library that cusotmer-developers use to ease working with a specific Azure service. There is one client library per service and per programming language.
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="45">
|
||||
<p data-line="45"><span data-line="45"></span><strong class="strong-star2">Package</strong><span data-line="45"></span>. This refers to a client library after it has been packaged for distribution for customer-developers to consume. Examples are:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="46">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="46"><span data-line="46"></span>A Nuget package for a .NET client library
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="47"><span data-line="47"></span>A Maven package for a Java library
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="48"><span data-line="48"></span>An NPM package for a JavaScript library
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="49"><span data-line="49"></span>A PiPI package for a Python library
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="50"><span data-line="50"></span>A GitHub repositiory for a Go library (NOTE: Go is not a supported language yet)
|
||||
</li></ul>
|
||||
</li></ul>
|
||||
<h2 id="sec-pre-requisites" class="h1" data-line="52" data-heading-depth="1" style="display:block"><span data-line="52"></span><span class="heading-before"><span class="heading-label">2</span>. </span><span data-line="52"></span>Pre-requisites</h2>
|
||||
<p class="p noindent" data-line="54"><span data-line="54"></span>Releasing an SDK component that provides a more convenient means of connecting to a service requires that the service itself be in a state where it has stablised.
|
||||
We can build SDK components whilst a service stablises, but we should never distribute a GA release until the service and the client library is stable.
|
||||
</p>
|
||||
<div id="stable-service" class="mustnot" data-line="57">
|
||||
<p class="p noindent" data-line="58"><span data-line="58"></span><a class='req-label' href='#stable-service'><span data-line="58"></span>⛔️<span data-line="58"></span></a><span data-line="58"></span> <span data-line="58"></span><strong class="strong-star2">DO NOT</strong><span data-line="58"></span> make a GA release of a SDK component until the underlying service is also in GA, with a stable protocol. </p></div>
|
||||
<div id="stable-swagger" class="mustnot" data-line="61">
|
||||
<p class="p noindent" data-line="62"><span data-line="62"></span><a class='req-label' href='#stable-swagger'><span data-line="62"></span>⛔️<span data-line="62"></span></a><span data-line="62"></span> <span data-line="62"></span><strong class="strong-star2">DO NOT</strong><span data-line="62"></span> make a GA release of a SDK component for a service whose protocol is based on a REST API until there is a stable GA Swagger specification available.</p></div><h2 id="sec-functionality" class="h1" data-line="65" data-heading-depth="1" style="display:block"><span data-line="65"></span><span class="heading-before"><span class="heading-label">3</span>. </span><span data-line="65"></span>Functionality</h2>
|
||||
<div id="support-all-service-features" class="must" data-line="67">
|
||||
<p class="p noindent" data-line="68"><span data-line="68"></span><a class='req-label' href='#support-all-service-features'><span data-line="68"></span>✅<span data-line="68"></span></a><span data-line="68"></span> <span data-line="68"></span><strong class="strong-star2">DO</strong><span data-line="68"></span> support 100% of the features provided by the Azure service the SDK component represents. Gaps in functionality cause confusion and frustration among developers.</p></div><h2 id="sec-operating-systems" class="h1" data-line="71" data-heading-depth="1" style="display:block"><span data-line="71"></span><span class="heading-before"><span class="heading-label">4</span>. </span><span data-line="71"></span>Operating Systems</h2>
|
||||
<div id="no-native-code" class="shouldnot" data-line="73">
|
||||
<p class="p noindent" data-line="74"><span data-line="74"></span><a class='req-label' href='#no-native-code'><span data-line="74"></span>⚠️<span data-line="74"></span></a><span data-line="74"></span> <span data-line="74"></span><strong class="strong-star2">YOU SHOULD NOT</strong><span data-line="74"></span> write platform-specific / native code. If any such code is required for proper functioning of the SDK component, it should be specifically called out as part of the review process and appropriate justification provided.</p></div>
|
||||
<div id="test-sample-apps-on-all-operating-systems" class="must" data-line="77">
|
||||
<p class="p noindent" data-line="78"><span data-line="78"></span><a class='req-label' href='#test-sample-apps-on-all-operating-systems'><span data-line="78"></span>✅<span data-line="78"></span></a><span data-line="78"></span> <span data-line="78"></span><strong class="strong-star2">DO</strong><span data-line="78"></span> test that sample apps execute as expected on Linux, Windows, and macOS.</p></div><h2 id="sec-github-requirements" class="h1" data-line="81" data-heading-depth="1" style="display:block"><span data-line="81"></span><span class="heading-before"><span class="heading-label">5</span>. </span><span data-line="81"></span>GitHub Requirements</h2>
|
||||
<div id="github-open-source" class="must" data-line="83">
|
||||
<p class="p noindent" data-line="84"><span data-line="84"></span><a class='req-label' href='#github-open-source'><span data-line="84"></span>✅<span data-line="84"></span></a><span data-line="84"></span> <span data-line="84"></span><strong class="strong-star2">DO</strong><span data-line="84"></span> ensure that all library code is public and open source on GitHub. Library code must be either in the<span data-line="84"></span> <a href="https://github.com/Azure/">Azure GitHub organization</a><span data-line="84"></span>
|
||||
or a module in the language-specific SDK <span data-line="85"></span>‘mono-repo’<span data-line="85"></span> (e.g.<span data-line="85"></span> <a href="https://github.com/Azure/azure-sdk-for-java">Azure SDK for Java</a><span data-line="85"></span>).
|
||||
If an independent repo is used then the repository name must be <span data-line="86"></span><code class="code code1">azure-[service-name]-[language]</code><span data-line="86"></span>.</p></div>
|
||||
<div id="github-be-open" class="should" data-line="89">
|
||||
<p class="p noindent" data-line="90"><span data-line="90"></span><a class='req-label' href='#github-be-open'><span data-line="90"></span>☑️<span data-line="90"></span></a><span data-line="90"></span> <span data-line="90"></span><strong class="strong-star2">YOU SHOULD</strong><span data-line="90"></span> develop in the open on GitHub. It is recommended to have your GitHub repo be set up and active at least a month prior to your initial release.</p></div>
|
||||
<div id="github-active" class="must" data-line="93">
|
||||
<p class="p noindent" data-line="94"><span data-line="94"></span><a class='req-label' href='#github-active'><span data-line="94"></span>✅<span data-line="94"></span></a><span data-line="94"></span> <span data-line="94"></span><strong class="strong-star2">DO</strong><span data-line="94"></span> remain active in GitHub. Your SDK component<span data-line="94"></span>'<span data-line="94"></span>s GitHub repo is your primary touch point with the developer community so it<span data-line="94"></span>'<span data-line="94"></span>s important to keep up with the activity there.
|
||||
Issues and pull requests on GitHub must have an authoritative comment within one week of filing.</p></div>
|
||||
<div id="github-review-open-source-guidelines" class="should" data-line="98">
|
||||
<p class="p noindent" data-line="99"><span data-line="99"></span><a class='req-label' href='#github-review-open-source-guidelines'><span data-line="99"></span>☑️<span data-line="99"></span></a><span data-line="99"></span> <span data-line="99"></span><strong class="strong-star2">YOU SHOULD</strong><span data-line="99"></span> review the Microsoft Open Source Guidelines<span data-line="99"></span>'<span data-line="99"></span> <a href="https://docs.opensource.microsoft.com/releasing/foster-your-community.html">community section</a><span data-line="99"></span> for more information on fostering a healthy open-source community.</p></div><h3 id="sec-readmespanspanmd" class="h2" data-line="102" data-heading-depth="2" style="display:block"><span data-line="102"></span><span class="heading-before"><span class="heading-label">5.1</span>. </span><span data-line="102"></span>README<span data-line="102"></span><span><span data-line="102"></span></span><span data-line="102"></span>.md</h3>
|
||||
<div id="github-readme" class="must" data-line="104">
|
||||
<p class="p noindent" data-line="105"><span data-line="105"></span><a class='req-label' href='#github-readme'><span data-line="105"></span>✅<span data-line="105"></span></a><span data-line="105"></span> <span data-line="105"></span><strong class="strong-star2">DO</strong><span data-line="105"></span> include in your GitHub repo a README<span data-line="105"></span><span><span data-line="105"></span></span><span data-line="105"></span>.md file that has the sections shown below. Rather than produce this from scratch, refer to the template readme<span data-line="105"></span><span><span data-line="105"></span></span><span data-line="105"></span>.md file and take that as a starting point.
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="107">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="107"><span data-line="107"></span>Short introduction of the service
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="108"><span data-line="108"></span>Maven
|
||||
|
||||
<ul class="ul list-dash compact" data-line="109">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="109"><span data-line="109"></span>Maven dependency fragment for latest GA release (with no version<span data-line="109"></span> <span data-line="109"></span>- link to central document for details on how to depend on Azure SDK BOM)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="110"><span data-line="110"></span>Maven dependency fragment for latest snapshot release
|
||||
</li></ul></li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="111"><span data-line="111"></span>Documentation
|
||||
|
||||
<ul class="ul list-dash compact" data-line="112">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="112"><span data-line="112"></span>Link to reference documentation
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="113"><span data-line="113"></span>Link to relevant quick starts and tutorials
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="114"><span data-line="114"></span>Samples table
|
||||
</li></ul></li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="115"><span data-line="115"></span>Contributing
|
||||
|
||||
<ul class="ul list-dash compact" data-line="116">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="116"><span data-line="116"></span>Must include a reference to the<span data-line="116"></span> <a href="https://opensource.microsoft.com/codeofconduct">Microsoft Open Source Code of Conduct</a><span data-line="116"></span> and a link to the CONTRIBUTING.md file
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="117"><span data-line="117"></span>Should encourage developers to seek support on Stack Overflow</li></ul></li></ul></div><h3 id="sec-contributingspanspanmd" class="h2" data-line="120" data-heading-depth="2" style="display:block"><span data-line="120"></span><span class="heading-before"><span class="heading-label">5.2</span>. </span><span data-line="120"></span>CONTRIBUTING<span data-line="120"></span><span><span data-line="120"></span></span><span data-line="120"></span>.md</h3>
|
||||
<div id="github-contributing" class="must" data-line="122">
|
||||
<p class="p noindent" data-line="123"><span data-line="123"></span><a class='req-label' href='#github-contributing'><span data-line="123"></span>✅<span data-line="123"></span></a><span data-line="123"></span> <span data-line="123"></span><strong class="strong-star2">DO</strong><span data-line="123"></span> include CONTRIBUTING<span data-line="123"></span><span><span data-line="123"></span></span><span data-line="123"></span>.md file in your GitHub repo, using it to describe the process by which contributors can make contributions to the project.
|
||||
An example CONTRIBUTING.md is provided by the<span data-line="124"></span> <a href="https://docs.opensource.microsoft.com/releasing/overview.html">Microsoft Open Source Guidelines</a><span data-line="124"></span>:
|
||||
</p>
|
||||
<pre class="para-block pre-fenced pre-fenced3" data-line="126" data-line-first="127" style="display:block"><code data-line="127"># 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.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., label, comment). Simply follow the
|
||||
instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
|
||||
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.</code></pre></div>
|
||||
<div id="github-contributing-extra" class="must" data-line="144">
|
||||
<p class="p noindent" data-line="145"><span data-line="145"></span><a class='req-label' href='#github-contributing-extra'><span data-line="145"></span>✅<span data-line="145"></span></a><span data-line="145"></span> <span data-line="145"></span><strong class="strong-star2">DO</strong><span data-line="145"></span> include any relevant processes and procedures must be documented, such as:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="147">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="147"><span data-line="147"></span>Pre-requisites for successfully building and testing
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="148"><span data-line="148"></span>How to run builds and tests
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="149"><span data-line="149"></span>Generating reference documentation and other reports (linters, code coverage, etc)</li></ul></div><h3 id="sec-licensespanspanmd" class="h2" data-line="152" data-heading-depth="2" style="display:block"><span data-line="152"></span><span class="heading-before"><span class="heading-label">5.3</span>. </span><span data-line="152"></span>LICENSE<span data-line="152"></span><span><span data-line="152"></span></span><span data-line="152"></span>.md</h3>
|
||||
<div id="github-license" class="must" data-line="154">
|
||||
<p class="p noindent" data-line="155"><span data-line="155"></span><a class='req-label' href='#github-license'><span data-line="155"></span>✅<span data-line="155"></span></a><span data-line="155"></span> <span data-line="155"></span><strong class="strong-star2">DO</strong><span data-line="155"></span> include a LICENSE<span data-line="155"></span><span><span data-line="155"></span></span><span data-line="155"></span>.md file containing your license text (which by default should be the standard MIT license).</p></div><h3 id="sec-codeowners" class="h2" data-line="158" data-heading-depth="2" style="display:block"><span data-line="158"></span><span class="heading-before"><span class="heading-label">5.4</span>. </span><span data-line="158"></span>CODEOWNERS</h3>
|
||||
<p class="p noindent" data-line="160"><span data-line="160"></span>CODEOWNERS is a GitHub standard to specify who is automatically assigned pull requests to review. This helps to prevent pull requests from languishing without review. GitHub can also be configured to require review from code owners before a pull request can be merged. Further reading is available from the following two URLs:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="162">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="162"><span data-line="162"></span><a href="https://blog.github.com/2017-07-06-introducing-code-owners/">https://blog.github.com/2017-07-06-introducing-code-owners/</a><span data-line="162"></span>
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="163"><span data-line="163"></span><a href="https://help.github.com/articles/about-codeowners/">https://help.github.com/articles/about-codeowners/</a><span data-line="163"></span>
|
||||
</li></ul>
|
||||
|
||||
<div id="github-codeowners" class="must" data-line="165">
|
||||
<p class="p noindent" data-line="166"><span data-line="166"></span><a class='req-label' href='#github-codeowners'><span data-line="166"></span>✅<span data-line="166"></span></a><span data-line="166"></span> <span data-line="166"></span><strong class="strong-star2">DO</strong><span data-line="166"></span> edit the root-level CODEOWNERS file to ensure that it is updated to redirect all pull requests for the directory of the SDK component to point to the relevant engineers of this component. If the SDK component will exist within its own repository, then a CODEOWNERS file must be introduced and configured appropriately.</p></div><h2 id="sec-language-specific-guidelines" class="h1" data-line="169" data-heading-depth="1" style="display:block"><span data-line="169"></span><span class="heading-before"><span class="heading-label">6</span>. </span><span data-line="169"></span>Language-Specific Guidelines</h2><h3 id="common-general" class="h2" data-line="171" data-heading-depth="2" style="display:block"><span data-line="171"></span><span class="heading-before"><span class="heading-label">6.1</span>. </span><span data-line="171"></span>General Guidelines</h3>
|
||||
<p class="p noindent" data-line="173"><span data-line="173"></span>These language-specific gudelines overrule language independent guidelines.
|
||||
</p>
|
||||
<div id="general-follow-language-guidelines" class="must" data-line="175">
|
||||
<p class="p noindent" data-line="176"><span data-line="176"></span><a class='req-label' href='#general-follow-language-guidelines'><span data-line="176"></span>✅<span data-line="176"></span></a><span data-line="176"></span> <span data-line="176"></span><strong class="strong-star2">DO</strong><span data-line="176"></span> provide SDKs for the following languages: C<span data-line="176"></span>#<span data-line="176"></span>, Java, Python, JavaScript.</p></div>
|
||||
<div id="general-ship-other-langs" class="may" data-line="179">
|
||||
<p class="p noindent" data-line="180"><span data-line="180"></span><a class='req-label' href='#general-ship-other-langs'><span data-line="180"></span>☑️<span data-line="180"></span></a><span data-line="180"></span> <span data-line="180"></span><strong class="strong-star2">YOU MAY</strong><span data-line="180"></span> provide SDKs for the following languages: Go, C++</p></div>
|
||||
<div class="todo note" data-line="183" style="display:block">
|
||||
<p class="p noindent" data-line="184"><span data-line="184"></span><a class='req-label' href='#'><span data-line="184"></span>✏️<span data-line="184"></span></a><span data-line="184"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="185"></span>This will result in partial coverage for optional languages. Is that OK?</p></div>
|
||||
<div id="general-support-cancellation" class="must" data-line="187">
|
||||
<p class="p noindent" data-line="188"><span data-line="188"></span><a class='req-label' href='#general-support-cancellation'><span data-line="188"></span>✅<span data-line="188"></span></a><span data-line="188"></span> <span data-line="188"></span><strong class="strong-star2">DO</strong><span data-line="188"></span> support cancellations.</p></div>
|
||||
<div id="general-support-retries" class="must" data-line="191">
|
||||
<p class="p noindent" data-line="192"><span data-line="192"></span><a class='req-label' href='#general-support-retries'><span data-line="192"></span>✅<span data-line="192"></span></a><span data-line="192"></span> <span data-line="192"></span><strong class="strong-star2">DO</strong><span data-line="192"></span> support retries</p></div>
|
||||
<div id="general-no-concrete-logging" class="mustnot" data-line="195">
|
||||
<p class="p noindent" data-line="196"><span data-line="196"></span><a class='req-label' href='#general-no-concrete-logging'><span data-line="196"></span>⛔️<span data-line="196"></span></a><span data-line="196"></span> <span data-line="196"></span><strong class="strong-star2">DO NOT</strong><span data-line="196"></span> depend on concrete logging, dependency injection, or configuration technologies.</p></div>
|
||||
<p class="p noindent" data-line="199"><span data-line="199"></span>The SDKs will be used in applications that might be using ther logging, DI, and configuration technologies of their choice.
|
||||
</p><h3 id="general-telemetry" class="h2" data-line="201" data-heading-depth="2" style="display:block"><span data-line="201"></span><span class="heading-before"><span class="heading-label">6.2</span>. </span><span data-line="201"></span>Telemetry</h3>
|
||||
<p class="p noindent" data-line="203"><span data-line="203"></span>Telemetry is used by service teams (not customers) to monitor what SDK a client is using to call into their service. Specifically, the service team can detect client OS, language, language version, and service SDK version. Some clients can prepend additional information indicating the name and version of the client application.
|
||||
</p>
|
||||
<div class="must" data-line="205">
|
||||
<p class="p noindent" data-line="206"><span data-line="206"></span><a class='req-label' href='#'><span data-line="206"></span>✅<span data-line="206"></span></a><span data-line="206"></span> <span data-line="206"></span><strong class="strong-star2">DO</strong><span data-line="206"></span> send telemetry information in the User-Agent header, with the header value in the the following format:
|
||||
</p>
|
||||
<pre class="para-block pre-fenced pre-fenced3" data-line="208" data-line-first="209" style="display:block"><code data-line="209">[<application_id>/<SPACE\>]<sdk_name>/<sdk_version>/<SPACE\><platform_information></code></pre>
|
||||
<ul class="ul list-dash compact" data-line="212">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="212"><span data-line="212"></span><code class="code code1"><application_id> ::=</code><span data-line="212"></span> optional application-specific string. The string is supplied by the user of the SDK, e.g. <span data-line="212"></span>“AzCopy/10.0.4-Preview”<span data-line="212"></span>
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="213"><span data-line="213"></span><code class="code code1"><sdk_name> ::=</code><span data-line="213"></span> name of the SDK, e.g. <span data-line="213"></span>“Azure-Storage-Blob”<span data-line="213"></span>
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="214"><span data-line="214"></span><code class="code code1"><sdk_version> ::=</code><span data-line="214"></span> the version of the SDK. Note: this is not the version of the service
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="215"><span data-line="215"></span><code class="code code1"><platform_information> ::=</code><span data-line="215"></span> information about the currently-executing OS and runtime, e.g. <span data-line="215"></span>“(NODE-VERSION v4.5.0; Windows_NT 10.0.14393)”</li></ul></div>
|
||||
<div id="general-example-user-agent-strings" class="example" data-line="218" style="display:block;margin:1ex 0pt">
|
||||
<p class="p noindent" data-line="219"><span data-line="219"></span><a class='req-label' href='#general-example-user-agent-strings'><span data-line="219"></span>Ex<span data-line="219"></span></a><span data-line="219"></span><span class="example-before"><strong class="strong-star2">Example <span class="example-label">1</span>.</strong> <span class="theorem-caption">(<span style="font-style:italic">Example User-Agent header values</span>)</span><br>
|
||||
</span><span data-line="219"></span>
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="221">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="221"><span data-line="221"></span>“Azure-Storage/1.4.0 (NODE-VERSION v4.5.0; Windows_NT 10.0.14393)”<span data-line="221"></span>
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="222"><span data-line="222"></span>“AzCopy/10.0.4-Preview Azure-Storage/1.4.0 (NODE-VERSION v4.5.0; Windows_NT 10.0.14393)”</li></ul></div>
|
||||
<p class="p noindent" data-line="225"><span data-line="225"></span>For details on the User-Agent header, see https://tools.ietf.org/html/rfc7231<span data-line="225"></span>#<span data-line="225"></span>section-5.5.3
|
||||
</p>
|
||||
<div class="note" data-line="227" style="display:block">
|
||||
<p class="p noindent" data-line="228"><span data-line="228"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Note</span></strong>.
|
||||
</span><span data-line="229"></span><a class='req-label' href='#'><span data-line="229"></span>⚠️<span data-line="229"></span></a><span data-line="229"></span> <span data-line="229"></span><strong class="strong-star2">NOTE</strong><span data-line="229"></span> Today, the <span data-line="229"></span><sdk_name><span data-line="229"></span> for all storage SDKs/packages (Blob, File, etc.) is simply <span data-line="229"></span>“Azure-Storage”<span data-line="229"></span>. The guideline above proposes that we standardize on full SDK names, e.g. <span data-line="229"></span>“Azure-Storage-Blob”<span data-line="229"></span>.</p></div>
|
||||
<div class="todo note" data-line="231" style="display:block">
|
||||
<p class="p noindent" data-line="232"><span data-line="232"></span><a class='req-label' href='#'><span data-line="232"></span>✏️<span data-line="232"></span></a><span data-line="232"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="233"></span>Provide the full list of SDK names.</p></div>
|
||||
<div class="todo note" data-line="235" style="display:block">
|
||||
<p class="p noindent" data-line="236"><span data-line="236"></span><a class='req-label' href='#'><span data-line="236"></span>✏️<span data-line="236"></span></a><span data-line="236"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="237"></span>Provide language-specific guidelines (and possibly shared library) for generating <span data-line="237"></span><platform_information></p></div>
|
||||
<div class="todo note" data-line="239" style="display:block">
|
||||
<p class="p noindent" data-line="240"><span data-line="240"></span><a class='req-label' href='#'><span data-line="240"></span>✏️<span data-line="240"></span></a><span data-line="240"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="241"></span>Provide shared library API for injecting telemetry information</p></div><h3 id="general-logging" class="h2" data-line="243" data-heading-depth="2" style="display:block"><span data-line="243"></span><span class="heading-before"><span class="heading-label">6.3</span>. </span><span data-line="243"></span>Logging</h3>
|
||||
<div id="general-logging-pluggable" class="must" data-line="245">
|
||||
<p class="p noindent" data-line="246"><span data-line="246"></span><a class='req-label' href='#general-logging-pluggable'><span data-line="246"></span>✅<span data-line="246"></span></a><span data-line="246"></span> <span data-line="246"></span><strong class="strong-star2">DO</strong><span data-line="246"></span> support pluggable loggers.</p></div>
|
||||
<div id="general-logging-levels" class="must" data-line="249">
|
||||
<p class="p noindent" data-line="250"><span data-line="250"></span><a class='req-label' href='#general-logging-levels'><span data-line="250"></span>✅<span data-line="250"></span></a><span data-line="250"></span> <span data-line="250"></span><strong class="strong-star2">DO</strong><span data-line="250"></span> emit the following log levels: Verbose (i.e. details), Informational (things happened), Warning (might be a problem or not), and Error.</p></div>
|
||||
<div id="general-logging-no-sensitive-info" class="mustnot" data-line="253">
|
||||
<p class="p noindent" data-line="254"><span data-line="254"></span><a class='req-label' href='#general-logging-no-sensitive-info'><span data-line="254"></span>⛔️<span data-line="254"></span></a><span data-line="254"></span> <span data-line="254"></span><strong class="strong-star2">DO NOT</strong><span data-line="254"></span> send sensitive information to the logs, e.g. remove account keys when logging headers.</p></div>
|
||||
<div id="general-logging-warn-if-slow-request" class="must" data-line="257">
|
||||
<p class="p noindent" data-line="258"><span data-line="258"></span><a class='req-label' href='#general-logging-warn-if-slow-request'><span data-line="258"></span>✅<span data-line="258"></span></a><span data-line="258"></span> <span data-line="258"></span><strong class="strong-star2">DO</strong><span data-line="258"></span> log a Warning message, if a request takes longer than some specified threshold. The default threshold is 3 seconds.</p></div>
|
||||
<div id="general-logging-requests-in-info" class="must" data-line="261">
|
||||
<p class="p noindent" data-line="262"><span data-line="262"></span><a class='req-label' href='#general-logging-requests-in-info'><span data-line="262"></span>✅<span data-line="262"></span></a><span data-line="262"></span> <span data-line="262"></span><strong class="strong-star2">DO</strong><span data-line="262"></span> log request line, response line, and headers, as Informational message.</p></div>
|
||||
<div id="general-logging-error-for-bad-status" class="must" data-line="265">
|
||||
<p class="p noindent" data-line="266"><span data-line="266"></span><a class='req-label' href='#general-logging-error-for-bad-status'><span data-line="266"></span>✅<span data-line="266"></span></a><span data-line="266"></span> <span data-line="266"></span><strong class="strong-star2">DO</strong><span data-line="266"></span> log an Error message, if a response comes back with a status codes between 400-599.</p></div>
|
||||
<p class="p noindent" data-line="269"><span data-line="269"></span>Some services use status codes in this range in normal course of operation, e.g. implement an <span data-line="269"></span>“exists”<span data-line="269"></span> check by returning 404 (not found). In such situations, the particular service might opt out from logging such status code as error.
|
||||
</p>
|
||||
<div id="general-logging-warning-if-retry" class="must" data-line="271">
|
||||
<p class="p noindent" data-line="272"><span data-line="272"></span><a class='req-label' href='#general-logging-warning-if-retry'><span data-line="272"></span>✅<span data-line="272"></span></a><span data-line="272"></span> <span data-line="272"></span><strong class="strong-star2">DO</strong><span data-line="272"></span> log a Warning message, if a service call needs to be retried.</p></div>
|
||||
<div id="general-logging-info-if-cancelled" class="must" data-line="275">
|
||||
<p class="p noindent" data-line="276"><span data-line="276"></span><a class='req-label' href='#general-logging-info-if-cancelled'><span data-line="276"></span>✅<span data-line="276"></span></a><span data-line="276"></span> <span data-line="276"></span><strong class="strong-star2">DO</strong><span data-line="276"></span> log an Informational message, if a service call is cancelled.</p></div>
|
||||
<div id="general-logging-error-if-exceptions" class="must" data-line="279">
|
||||
<p class="p noindent" data-line="280"><span data-line="280"></span><a class='req-label' href='#general-logging-error-if-exceptions'><span data-line="280"></span>✅<span data-line="280"></span></a><span data-line="280"></span> <span data-line="280"></span><strong class="strong-star2">DO</strong><span data-line="280"></span> log exceptions thrown as an Error message. If the log level set to Verbose, append stack trace information to the message.</p></div>
|
||||
<div id="general-logging-use-syslog" class="must" data-line="283">
|
||||
<p class="p noindent" data-line="284"><span data-line="284"></span><a class='req-label' href='#general-logging-use-syslog'><span data-line="284"></span>✅<span data-line="284"></span></a><span data-line="284"></span> <span data-line="284"></span><strong class="strong-star2">DO</strong><span data-line="284"></span> log failures (exceptions and error status codes), regardless logging level, to the event log on Windows and the syslog on Linux, i.e. this cannot be turned off by the SDK user unless they replace the pipeline.</p></div>
|
||||
<div class="todo note" data-line="287" style="display:block">
|
||||
<p class="p noindent" data-line="288"><span data-line="288"></span><a class='req-label' href='#'><span data-line="288"></span>✏️<span data-line="288"></span></a><span data-line="288"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="289"></span>describe format/syntax of the log messages.</p></div>
|
||||
<div class="todo note" data-line="291" style="display:block">
|
||||
<p class="p noindent" data-line="292"><span data-line="292"></span><a class='req-label' href='#'><span data-line="292"></span>✏️<span data-line="292"></span></a><span data-line="292"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="293"></span>provide and describe pipeline APIs for logging.</p></div><h3 id="general-retry" class="h2" data-line="295" data-heading-depth="2" style="display:block"><span data-line="295"></span><span class="heading-before"><span class="heading-label">6.4</span>. </span><span data-line="295"></span>Retry</h3>
|
||||
<p class="p noindent" data-line="297"><span data-line="297"></span>There are many reasons why failure can occur when a client application attempts to send a network request to a service. Some examples are timeout, network infrastructure failures, service rejecting the request due to throttle/busy, service instance terminating due to service scale down, service instance going down to be replaced with another version, service crashing due to an unhandled exception, etc. By offering a built-in retry mechanism (with a default configuration overridable by the customer), our SDKs and the customer’s application become resilient to these kinds of failures. Note that some services charge real money for each try and so customers should be able to disable retries entirely if they prefer to save money over resiliency.
|
||||
</p>
|
||||
<div id="general-retry-configuration" class="must" data-line="299">
|
||||
<p class="p noindent" data-line="300"><span data-line="300"></span><a class='req-label' href='#general-retry-configuration'><span data-line="300"></span>✅<span data-line="300"></span></a><span data-line="300"></span> <span data-line="300"></span><strong class="strong-star2">DO</strong><span data-line="300"></span> offer the following configuration settings:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="302">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="302"><span data-line="302"></span>Retry policy (exponential or fixed)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="303"><span data-line="303"></span>Maximum number of tries (32-bit integer; 0=default, 1=1 try <span data-line="303"></span>&<span data-line="303"></span> no retries, 2=1 try <span data-line="303"></span>&<span data-line="303"></span> 1 retry, etc.)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="304"><span data-line="304"></span>Per-try timeout (timespan/duration; default=worst anticipated bandwidth times largest single request and response payloads)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="305"><span data-line="305"></span>Retry delay (timespan/duration; this is the delay for fixed policy, the delay is increased exponentially by this amount for the exponential policy)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="306"><span data-line="306"></span>Max retry delay (timespan/duration; the delay will never go over this amount)</li></ul></div>
|
||||
<div id="general-retry-available-if-supported" class="must" data-line="309">
|
||||
<p class="p noindent" data-line="310"><span data-line="310"></span><a class='req-label' href='#general-retry-available-if-supported'><span data-line="310"></span>✅<span data-line="310"></span></a><span data-line="310"></span> <span data-line="310"></span><strong class="strong-star2">DO</strong><span data-line="310"></span> offer additional retry mechanism if supported by the service</p></div>
|
||||
<ul class="ul list-dash compact" data-line="313">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="313"><span data-line="313"></span>For example, the Azure Storage Blob service supports retrying read operations against a secondary datacenter
|
||||
</li></ul>
|
||||
|
||||
<div id="general-retry-reset-on-retry" class="must" data-line="315">
|
||||
<p class="p noindent" data-line="316"><span data-line="316"></span><a class='req-label' href='#general-retry-reset-on-retry'><span data-line="316"></span>✅<span data-line="316"></span></a><span data-line="316"></span> <span data-line="316"></span><strong class="strong-star2">DO</strong><span data-line="316"></span> reset (or seek back to position 0) any request data stream before retrying a request</p></div>
|
||||
<div id="general-retry-honor-caller-cancellation" class="must" data-line="319">
|
||||
<p class="p noindent" data-line="320"><span data-line="320"></span><a class='req-label' href='#general-retry-honor-caller-cancellation'><span data-line="320"></span>✅<span data-line="320"></span></a><span data-line="320"></span> <span data-line="320"></span><strong class="strong-star2">DO</strong><span data-line="320"></span> honor any cancellation mechanism passed-in be the caller which can terminate the request before retried have been attempted.</p></div>
|
||||
<div id="general-retry-update-time-to-live" class="must" data-line="323">
|
||||
<p class="p noindent" data-line="324"><span data-line="324"></span><a class='req-label' href='#general-retry-update-time-to-live'><span data-line="324"></span>✅<span data-line="324"></span></a><span data-line="324"></span> <span data-line="324"></span><strong class="strong-star2">DO</strong><span data-line="324"></span> update any query parameter or request header that gets sent to the service telling it how much time the service has to process the individual request attempt.</p></div>
|
||||
<div id="general-retry-on-hardware-network-failure" class="must" data-line="327">
|
||||
<p class="p noindent" data-line="328"><span data-line="328"></span><a class='req-label' href='#general-retry-on-hardware-network-failure'><span data-line="328"></span>✅<span data-line="328"></span></a><span data-line="328"></span> <span data-line="328"></span><strong class="strong-star2">DO</strong><span data-line="328"></span> retry in the case of a hardware network failure as it may self-correct</p></div>
|
||||
<div id="general-retry-on-service-not-found" class="must" data-line="331">
|
||||
<p class="p noindent" data-line="332"><span data-line="332"></span><a class='req-label' href='#general-retry-on-service-not-found'><span data-line="332"></span>✅<span data-line="332"></span></a><span data-line="332"></span> <span data-line="332"></span><strong class="strong-star2">DO</strong><span data-line="332"></span> retry in the case of a service not found error as the service may be coming back online or a load balancer may be reconfiguring itself.</p></div>
|
||||
<div id="general-retry-on-per-try-timeout" class="must" data-line="335">
|
||||
<p class="p noindent" data-line="336"><span data-line="336"></span><a class='req-label' href='#general-retry-on-per-try-timeout'><span data-line="336"></span>✅<span data-line="336"></span></a><span data-line="336"></span> <span data-line="336"></span><strong class="strong-star2">DO</strong><span data-line="336"></span> retry in the case of a per-try timeout</p></div>
|
||||
<div id="general-retry-if-throttled" class="must" data-line="339">
|
||||
<p class="p noindent" data-line="340"><span data-line="340"></span><a class='req-label' href='#general-retry-if-throttled'><span data-line="340"></span>✅<span data-line="340"></span></a><span data-line="340"></span> <span data-line="340"></span><strong class="strong-star2">DO</strong><span data-line="340"></span> retry if the service successfully responds indicating that it is throttle requests.</p></div>
|
||||
<div id="general-retry-no-retry-if-successfully-failed" class="mustnot" data-line="343">
|
||||
<p class="p noindent" data-line="344"><span data-line="344"></span><a class='req-label' href='#general-retry-no-retry-if-successfully-failed'><span data-line="344"></span>⛔️<span data-line="344"></span></a><span data-line="344"></span> <span data-line="344"></span><strong class="strong-star2">DO NOT</strong><span data-line="344"></span> retry if the service successfully responds indicating that the requested operation failed.</p></div><h3 id="sec-cancellation-timeouts" class="h2" data-line="347" data-heading-depth="2" style="display:block"><span data-line="347"></span><span class="heading-before"><span class="heading-label">6.5</span>. </span><span data-line="347"></span>Cancellation <span data-line="347"></span>&<span data-line="347"></span> Timeouts</h3>
|
||||
<p class="p noindent" data-line="349"><span data-line="349"></span>When an application makes a network request, the network infrastrucutre(like routers) and the called service may take a long time to respond and, in fact, may never respond. A well-written application SHOULD NEVER give up its control to the network infrasture or service. To ensure that users of our SDKs can keep control of their application, SDK methods that perform I/O operations MUST accept some kind of cancellation <span data-line="349"></span>&<span data-line="349"></span> timeout mechanism specific to the programming language.
|
||||
</p>
|
||||
<p class="p indent" data-line="351"><span data-line="351"></span>Here are some examples as to why this is so important:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="353">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="353"><span data-line="353"></span>When an orchestrator needs to terminate a service (due to scale in, reconfiguration, or upgrading to a new version), the orchestrator typically notifies a running service stance by simulating a Ctrl+C or SIGINT. When the service recieves this, it should terminate as quickly <span data-line="353"></span>&<span data-line="353"></span> gracefully as possible by setting a cancelation mechanism which should be honored by ALL functions that are currently in-flight.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="354"><span data-line="354"></span>When a customer<span data-line="354"></span>'<span data-line="354"></span>s webserver receives a request, it may set a time-limit indicating how much time it is allowing before it must give a response to the customer.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="355"><span data-line="355"></span>When a customer<span data-line="355"></span>'<span data-line="355"></span>s GUI appication makes a request to an Azure service via our SDK, the GUI might offer a cancel button so that the end-user can indicate that they are no longer in waiting for an operation or operations to complete.
|
||||
</li></ul>
|
||||
|
||||
<p class="p noindent" data-line="357"><span data-line="357"></span>The best way for customers to work with cancellation is to think of cancellation objects as forming a tree. For example:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="359">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="359"><span data-line="359"></span>Cancelling a parent automatically cancels it’s children.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="360"><span data-line="360"></span>Children can timeout sooner than their parent but cannot extend the time.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="361"><span data-line="361"></span>Cancellation can happen due to timeout or due to a manual/explicit cancel.
|
||||
</li></ul>
|
||||
|
||||
<p class="p noindent" data-line="363"><span data-line="363"></span>Here is an example of how an application would use the tree of cancellations:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="365">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="365"><span data-line="365"></span>When an application starts, it should create a cancellation object that represents the entire application; this object is explicitly terminated in response to the application receiving a Ctrl+C or SIGINT notification.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="366"><span data-line="366"></span>When a webserver receives an incoming request, it would create a new cancellation node that is a child of the application node. The new node would specify a maximum time that the webserver is allowing beforeto operate on the incoming request.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="367"><span data-line="367"></span>As part of operating on the incoming request, the webserver might need to make multiple requests to other services (like a database). If these requests can be made serially or in parallel, then they might share the previously-created cancellation node<span data-line="367"></span>'<span data-line="367"></span>s timeout. However, if the webserver wants to limit the time spent on 1 or more the requests, it can create a new cancellation node (with the desired timeout value) and make this node a child of the incoming request<span data-line="367"></span>'<span data-line="367"></span>s node; this way, the individual request timesout either when the overall request timesout or when the max time for this operation timeout<span data-line="367"></span> <span data-line="367"></span>- whichever happens first.
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="368"><span data-line="368"></span>Note that if multiple request are made in parallel, it is common for the customer to want to cancel all of them if any one of them fails. This should be a supported scenario.
|
||||
</li></ul>
|
||||
<h3 id="sec-dependencies" class="h2" data-line="370" data-heading-depth="2" style="display:block"><span data-line="370"></span><span class="heading-before"><span class="heading-label">6.6</span>. </span><span data-line="370"></span>Dependencies</h3>
|
||||
<p class="p noindent" data-line="372"><span data-line="372"></span>Many programming languages do not allow a customer to load multiple versions of the same package. So, if we have an SDK that requires v3 of package Foo and the customer wants to use v5 of package Foo, then the customer cannot build their application. This means that our SDKs should not dependend on any additional packages. In addition, customer applications must be able to deploy as fast as possible onto datacetner virtual machines. Removing additional code (like dependencies) improves deployment performance.
|
||||
</p>
|
||||
<div class="mustnot" data-line="374">
|
||||
<p class="p noindent" data-line="375"><span data-line="375"></span><a class='req-label' href='#'><span data-line="375"></span>⛔️<span data-line="375"></span></a><span data-line="375"></span> <span data-line="375"></span><strong class="strong-star2">DO NOT</strong><span data-line="375"></span> be dependent on any other packages</p></div>
|
||||
<div class="must" data-line="378">
|
||||
<p class="p noindent" data-line="379"><span data-line="379"></span><a class='req-label' href='#'><span data-line="379"></span>✅<span data-line="379"></span></a><span data-line="379"></span> <span data-line="379"></span><strong class="strong-star2">DO</strong><span data-line="379"></span> copy <span data-line="379"></span>&<span data-line="379"></span> paste other required code into the SDK package in order to avoid taking a dependency on another package. Make sure that you are not violating any licensing agreements.</p></div>
|
||||
<p class="p noindent" data-line="382"><span data-line="382"></span>1.5.3 :warning: <span data-line="382"></span><strong class="strong-star2">NOTE</strong><span data-line="382"></span> For some languages (most notably Java) you will have no choice but to take dependency on other packages. You must only do this if you truely have no other way to avoid taking the dependency.
|
||||
</p><h3 id="sec-configuration" class="h2" data-line="384" data-heading-depth="2" style="display:block"><span data-line="384"></span><span class="heading-before"><span class="heading-label">6.7</span>. </span><span data-line="384"></span>Configuration</h3>
|
||||
<div class="must" data-line="386">
|
||||
<p class="p noindent" data-line="387"><span data-line="387"></span><a class='req-label' href='#'><span data-line="387"></span>✅<span data-line="387"></span></a><span data-line="387"></span> <span data-line="387"></span><strong class="strong-star2">DO</strong><span data-line="387"></span> allow any customer configuration or customization via SDK functions or properties as this allos the cusomter code to determine how to configure SDK options and also how to expose those SDK options to the customer<span data-line="387"></span>'<span data-line="387"></span>s users.</p></div>
|
||||
<div class="mustnot" data-line="390">
|
||||
<p class="p noindent" data-line="391"><span data-line="391"></span><a class='req-label' href='#'><span data-line="391"></span>⛔️<span data-line="391"></span></a><span data-line="391"></span> <span data-line="391"></span><strong class="strong-star2">DO NOT</strong><span data-line="391"></span> allow any customer configuration or customization via a shared resource like a file or environment variable as this prevents different configurations to exist at the same time.</p></div><h3 id="sec-other-topics-to-be-covered" class="h2" data-line="394" data-heading-depth="2" style="display:block"><span data-line="394"></span><span class="heading-before"><span class="heading-label">6.8</span>. </span><span data-line="394"></span>Other topics to be covered</h3>
|
||||
<ul class="ul list-dash loose" data-line="396">
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="396">
|
||||
<p data-line="396"><span data-line="396"></span>Tracing
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="397">
|
||||
<p data-line="397"><span data-line="397"></span>Versioning
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="398">
|
||||
<p data-line="398"><span data-line="398"></span>Authorization (credentials)
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="399">
|
||||
<p data-line="399"><span data-line="399"></span>Error/Exception handling
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="400">
|
||||
<p data-line="400"><span data-line="400"></span>Packaging (Brian)
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="401">
|
||||
<p data-line="401"><span data-line="401"></span>Namespaces (Krzysztof)
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="402">
|
||||
<p data-line="402"><span data-line="402"></span>High level structure of APIs (Krzysztof)
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="403">
|
||||
<p data-line="403"><span data-line="403"></span>Docs (reference, Samples, Quick Starts) (Jonathan Giles)
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="404">
|
||||
<p data-line="404"><span data-line="404"></span>UX Study
|
||||
</p></li>
|
||||
<li class="li ul-li list-dash-li loose-li" data-line="406">
|
||||
<p data-line="406"><span data-line="406"></span>Engineering TOC:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="407">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="407"><span data-line="407"></span>Linter
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="408"><span data-line="408"></span>Packaging
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="409"><span data-line="409"></span>Signing
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="410"><span data-line="410"></span>Project Structure
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="411"><span data-line="411"></span>Repos
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="412"><span data-line="412"></span>License
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="413"><span data-line="413"></span>Testing (unit <span data-line="413"></span>&<span data-line="413"></span> E2E)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="414"><span data-line="414"></span>Supported versions
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="415"><span data-line="415"></span>Platform Support
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="416"><span data-line="416"></span>Stress
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="417"><span data-line="417"></span>Performance
|
||||
</li></ul>
|
||||
</li></ul>
|
||||
<h2 id="sec-c-specific-guidelines" class="h1" data-line="419" data-heading-depth="1" style="display:block"><span data-line="419"></span><span class="heading-before"><span class="heading-label">7</span>. </span><span data-line="419"></span>C<span data-line="419"></span>#<span data-line="419"></span> Specific Guidelines</h2><h3 id="sec-general-net-api-design" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:1" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:1"></span><span class="heading-before"><span class="heading-label">7.1</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:1"></span>General .NET API Design</h3>
|
||||
<div id="dotnet-follow-official-framework-guidelines" class="must" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:3">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span><a class='req-label' href='#dotnet-follow-official-framework-guidelines'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span>✅<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span><strong class="strong-star2">DO</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span> Follow the official<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span> <a href="https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/">Framework Design Guidelines</a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:4"></span>. See Appendix A (at the end of this document) for design guidelines that are commonly overlooked in existing Azure SDKs.
|
||||
</p>
|
||||
<p class="p indent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:6"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:6"></span><strong class="strong-star2">NOTE</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:6"></span> additional guidelines in this section overrule the Framework Design Guidelines</p></div>
|
||||
<div id="dotnet-use-azure-pipeline" class="must" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:9">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span><a class='req-label' href='#dotnet-use-azure-pipeline'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span>✅<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span><strong class="strong-star2">DO</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span> Use the Azure HTTP Pipeline to implement all methods that call Azure services. The pipeline takes care of many<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span> <a href="#common-general" class="localref">General Azure SDK Guidelines</a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:10"></span>, e.g. telemetry, logging, retries, mockability. Details of the pipeline design and usage are described in Appendix B below.</p></div><h3 id="sec-basic-azure-sdk-design-pattern" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:13" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:13"></span><span class="heading-before"><span class="heading-label">7.2</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:13"></span>Basic Azure SDK Design Pattern</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:15"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:15"></span>TODO:
|
||||
This scection describes the basic shape of a typical Azure SDK:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:18">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:18"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:18"></span>basic shape of the client types
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:19"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:19"></span>basic shape of service call methods
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:20"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:20"></span>cancellations
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:21"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:21"></span>return type (Response<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:21"></span><T><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:21"></span>) of service methods
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:22"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:22"></span>pipeline
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:23"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:23"></span>customizing service client and service method calls
|
||||
</li></ul>
|
||||
<h3 id="sec-naming-gudelines" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:25" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:25"></span><span class="heading-before"><span class="heading-label">7.3</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:25"></span>Naming Gudelines</h3><h4 id="sec-namespace-naming" class="h3" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:27" data-heading-depth="3" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:27"></span><span class="heading-before"><span class="heading-label">7.3.1</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:27"></span>Namespace Naming</h4>
|
||||
<div id="dotnet-namespace-registration" class="must" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:29">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span><a class='req-label' href='#dotnet-namespace-registration'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span>✅<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span><strong class="strong-star2">DO</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span> register all namespaces with adparch<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span>@microsoft.com<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:30"></span>,
|
||||
i.e. send email about your proposed namespaces to this address to start a discussion.</p></div>
|
||||
<div id="dotnet-namespace-format" class="must" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:35">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span><a class='req-label' href='#dotnet-namespace-format'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span>✅<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span><strong class="strong-star2">DO</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span> adhere to the following scheme when choosing a namespace: <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span><code class="code code1">Azure.<group>.<service>[.<feature>]</code><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span>. For example, <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span><code class="code code1">Azure.Storage.Blobs</code><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span>, <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:36"></span><code class="code code1">Azure.CognitiveServices.Speech.Recognition</code></p></div>
|
||||
<div id="dotnet-namespace-format-service-name" class="mustnot" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:39">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span><a class='req-label' href='#dotnet-namespace-format-service-name'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span>⛔️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span><strong class="strong-star2">DO NOT</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span> place service API in second level namespace, e.g. <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:40"></span><code class="code code1">Azure.KeyVault</code></p></div>
|
||||
<div id="dotnet-namespace-format-pre-approved" class="should" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:43">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"></span><a class='req-label' href='#dotnet-namespace-format-pre-approved'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"></span>☑️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"></span><strong class="strong-star2">YOU SHOULD</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:44"></span> use one of the following pre-approved namespace groups:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:46">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:46"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:46"></span>Azure.Diagnostics (e.g. Azure.Diagnostics.OperationalInsights)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:47"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:47"></span>Azure.Cognitive (e.g. Azure.Cognitive.FaceRecognition)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:48"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:48"></span>Azure.Iot (e.g. Azure.Iot.Hub)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:49"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:49"></span>Azure.Networking (e.g. Azure.Networking.EventHub)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:50"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:50"></span>Azure.Runtime (e.g. Azure.Runtime.VirtualMachines)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:51"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:51"></span>Azure.Security (e.g. Azure.Security.KeyVault)
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:52"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:52"></span>Azure.Storage (e.g. Azure.Storage.Blobs)</li></ul></div><h4 id="sec-type-naming" class="h3" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:55" data-heading-depth="3" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:55"></span><span class="heading-before"><span class="heading-label">7.3.2</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:55"></span>Type Naming</h4>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:57"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:57"></span>TODO: XxxClient, XxxResource, etc.
|
||||
</p><h3 id="sec-packaging-and-versioning" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:59" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:59"></span><span class="heading-before"><span class="heading-label">7.4</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:59"></span>Packaging and Versioning</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:61"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:61"></span>TODO
|
||||
</p><h3 id="sec-error-reporting" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:63" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:63"></span><span class="heading-before"><span class="heading-label">7.5</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:63"></span>Error Reporting</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:65"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:65"></span>TODO
|
||||
</p><h3 id="sec-authentication" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:67" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:67"></span><span class="heading-before"><span class="heading-label">7.6</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:67"></span>Authentication</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:69"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:69"></span>TODO
|
||||
</p><h3 id="sec-repository-guidelines" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:71" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:71"></span><span class="heading-before"><span class="heading-label">7.7</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:71"></span>Repository Guidelines</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:73"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:73"></span>TODO:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:75">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:75"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:75"></span>source code
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:76"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:76"></span>tests
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:77"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:77"></span>documentation
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:78"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:78"></span>samples
|
||||
</li></ul>
|
||||
<h3 id="sec-common-type-usage" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:80" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:80"></span><span class="heading-before"><span class="heading-label">7.8</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:80"></span>Common Type Usage</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:82"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:82"></span>TODO:
|
||||
</p>
|
||||
<ul class="ul list-dash compact" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:84">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:84"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:84"></span>Etag
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:85"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:85"></span>Response<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:85"></span><<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:85"></span>T<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:85"></span>><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:85"></span>
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:86"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:86"></span>System.Uri
|
||||
</li></ul>
|
||||
<h3 id="sec-commonly-overlooked-net-api-design-guidelines" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:88" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:88"></span><span class="heading-before"><span class="heading-label">7.A</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:88"></span>Commonly Overlooked .NET API Design Guidelines</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:90"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:90"></span>Some .NET Design Guidelines have been notoriously overlooked in existing Azure SDKs. This section serves as a way to highlight these guidelines.
|
||||
</p>
|
||||
<div id="dotnet-no-abstractions" class="mustnot" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:92">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"></span><a class='req-label' href='#dotnet-no-abstractions'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"></span>⛔️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"></span><strong class="strong-star2">DO NOT</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:93"></span> have abstractions (interfaces of abstract classes) unless types both implement and consume them (i.e. you have parameters typed as the abstraction).</p></div>
|
||||
<div id="dotnet-no-interfaces-for-abstract-classes" class="mustnot" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:96">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"></span><a class='req-label' href='#dotnet-no-interfaces-for-abstract-classes'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"></span>⛔️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"></span><strong class="strong-star2">DO NOT</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:97"></span> use interfaces if you can use abstract classes. The only reasons to use an interface are: a) you need to “multiple-inherit”, b) you want structs to implement and abstraction.</p></div>
|
||||
<div id="dotnet-no-generic-terms" class="mustnot" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:100">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"></span><a class='req-label' href='#dotnet-no-generic-terms'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"></span>⛔️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"></span><strong class="strong-star2">DO NOT</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:101"></span> use very generic words and terms for type names, e.g. do not use names like “OperationResponse”, “DataCollection” etc.</p></div>
|
||||
<div id="dotnet-no-unclear-parameter-types" class="shouldnot" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:104">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"></span><a class='req-label' href='#dotnet-no-unclear-parameter-types'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"></span>⚠️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"></span><strong class="strong-star2">YOU SHOULD NOT</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:105"></span> use parameters types where it’s not clear what valid values are supported, e.g. string parameters are often like that.</p></div>
|
||||
<div id="dotnet-no-empty-types" class="mustnot" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:108">
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"></span><a class='req-label' href='#dotnet-no-empty-types'><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"></span>⛔️<span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"></span></a><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"></span> <span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"></span><strong class="strong-star2">DO NOT</strong><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:109"></span> have empty types (types with no members)</p></div><h3 id="sec-azure-http-pipeline" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:112" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:112"></span><span class="heading-before"><span class="heading-label">7.B</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:112"></span>Azure Http Pipeline</h3>
|
||||
<p class="p noindent" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:114"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:114"></span>TODO:
|
||||
For now just link to sources: https://github.com/Azure/azure-sdk-for-net-lab/tree/master/Core/Azure.Core
|
||||
Once we publish Nuget package, this will be updated.
|
||||
</p><h3 id="sec-appendix-z--todo" class="h2" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:118" data-heading-depth="2" style="display:block"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:118"></span><span class="heading-before"><span class="heading-label">7.C</span>. </span><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:118"></span>Appendix Z: TODO</h3>
|
||||
<ul class="ul list-dash compact" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:120">
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:120"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:120"></span>integration with ASP.NET application model
|
||||
</li>
|
||||
<li class="li ul-li list-dash-li compact-li" data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:121"><span data-line="421;./docs/design/common/../dotnet/DesignGuidelines.mdk:121"></span>performance
|
||||
</li></ul>
|
||||
<h2 id="sec-java-specific-guidelines" class="h1" data-line="423" data-heading-depth="1" style="display:block"><span data-line="423"></span><span class="heading-before"><span class="heading-label">8</span>. </span><span data-line="423"></span>Java Specific Guidelines</h2>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:1"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:1"></span>This section covers Java-specific requirements to successfully implement and release a Java SDK component for Azure, that must be followed in addition to the common guidelines presented above. There exists a separate document for<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:1"></span> <a href="https://github.com/Azure/azure-sdk/blob/master/docs/design/java/BestPractices.md">Java best practices</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:1"></span> that teams should also endeavour to follow.
|
||||
</p><h3 id="java-scope" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:3" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:3"></span><span class="heading-before"><span class="heading-label">8.1</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:3"></span>Scope</h3>
|
||||
<div id="java-scope-inclusion" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:5">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span><a class='req-label' href='#java-scope-inclusion'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span> use the Maven group ID of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span><code class="code code1">com.azure</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span>, and the Java package name of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span><code class="code code1">com.azure.*</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:6"></span>, for all Java Azure SDK components. All SDK components in this namespace must follow the requirements outlined in this specification document.</p></div>
|
||||
<div id="java-scope-outside-components" class="may" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:9">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span><a class='req-label' href='#java-scope-outside-components'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span>☑️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span><strong class="strong-star2">YOU MAY</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span> follow the requirements outlined in this specification even if your namespace is not <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span><code class="code code1">com.azure</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:10"></span>- most of these requirements exist to ensure best practices are followed.</p></div><h3 id="sec-platform-support" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:13" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:13"></span><span class="heading-before"><span class="heading-label">8.2</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:13"></span>Platform Support</h3><h4 id="sec-operating-systems" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:15" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:15"></span><span class="heading-before"><span class="heading-label">8.2.1</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:15"></span>Operating Systems</h4>
|
||||
<div id="android-support" class="may" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:17">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"></span><a class='req-label' href='#android-support'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"></span>☑️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"></span><strong class="strong-star2">YOU MAY</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:18"></span> test against Android to ensure compatibility.</p></div><h4 id="sec-supported-java-versions" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:21" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:21"></span><span class="heading-before"><span class="heading-label">8.2.2</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:21"></span>Supported Java Versions</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:23"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:23"></span>All Azure SDK components are baselined on Java 8. Developers are encouraged to make use of the benefits offered in Java 8, such as streams, lambda expressions, new date/time API, etc.
|
||||
</p>
|
||||
<div id="java-do-not-exceed-jdk-baseline-features" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:25">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"></span><a class='req-label' href='#java-do-not-exceed-jdk-baseline-features'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:26"></span> use any language or API feature from a release of Java beyond Java 8. </p></div>
|
||||
<div id="java-ensure-jdk-baseline-compilation" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:29">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"></span><a class='req-label' href='#java-ensure-jdk-baseline-compilation'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:30"></span> test to ensure that all code compiles and runs as expected on Java 8.</p></div>
|
||||
<div id="java-avoid-private-impl" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:33">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span><a class='req-label' href='#java-avoid-private-impl'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span> use any private implementation API, such as those in the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span><code class="code code1">com.sun.*</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:34"></span> namespace, as these classes are unavailable from JDK 9 onwards. </p></div>
|
||||
<div id="java-ensure-jdk-lts-compilation" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:37">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"></span><a class='req-label' href='#java-ensure-jdk-lts-compilation'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:38"></span> compile against the latest Java long-term support release, to ensure that code continues to compile, and unit tests continue to run and pass. It is critical that when this is performed, that the Maven build configuration is temporarily adjusted to use the Java LTS APIs only.</p></div>
|
||||
<div id="java-jdk-build-target" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:41">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span><a class='req-label' href='#java-jdk-build-target'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span> build and test SDK components against a freely-available, open source, non-commercial build of OpenJDK (e.g.<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span> <a href="http://adoptopenjdk.net">AdoptOpenJDK</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span> or<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span> <a href="https://www.azul.com/downloads/zulu/">Azule Zulu</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:42"></span>), rather than Oracle JDK or any other commercial JDK build.</p></div><h3 id="sec-versioning" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:45" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:45"></span><span class="heading-before"><span class="heading-label">8.3</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:45"></span>Versioning</h3>
|
||||
<div id="java-use-semver" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:47">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span><a class='req-label' href='#java-use-semver'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span> ensure that all Maven releases are versioned using<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span> <a href="https://semver.org/">semantic versioning</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:48"></span>.</p></div>
|
||||
<div id="java-no-0-majors" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:51">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"></span><a class='req-label' href='#java-no-0-majors'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:52"></span> have releases of SDK components with a major version of 0, even for early preview releases.</p></div>
|
||||
<div class="todo note" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:55" style="display:block">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:56"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:56"></span><a class='req-label' href='#'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:56"></span>✏️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:56"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:56"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:57"></span>Include wider versioning discussion<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:57"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:57"></span>- side by side, connecting to multiple service versions at once, etc. This is<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:57"></span> <a href="https://github.com/Azure/azure-sdk/blob/master/docs/design/java/Versioning.md">currently covered in a separate discussion document</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:57"></span> whilst being worked through.</p></div><h4 id="sec-beta-api" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:59" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:59"></span><span class="heading-before"><span class="heading-label">8.3.1</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:59"></span>Beta API</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:61"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:61"></span>API needs sufficient <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:61"></span>‘bake time’<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:61"></span> to ensure it works in the real world. Rushing to have all API ready for the next release often leads to API regrets, many of which could have been avoided if API could have been reviewed by more users before being committed to.
|
||||
</p>
|
||||
<div id="java-use-deprecated-for-feature-dev" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:63">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span><a class='req-label' href='#java-use-deprecated-for-feature-dev'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span> use the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span><code class="code code1">@Beta</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:64"></span> annotation for API that are under development.</p></div>
|
||||
<div id="java-explain-experimental-features" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:67">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"></span><a class='req-label' href='#java-explain-experimental-features'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:68"></span> provide sufficient explanation to clarify that the API is experimental and may change.</p></div>
|
||||
<div id="java-beta-is-short-term" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:71">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"></span><a class='req-label' href='#java-beta-is-short-term'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:72"></span> remove all beta API annotations before any GA release.</p></div><h4 id="sec-snapshot-releases" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:75" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:75"></span><span class="heading-before"><span class="heading-label">8.3.2</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:75"></span>Snapshot Releases</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:77"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:77"></span>Snapshot releases have a semver version number of the form <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:77"></span><code class="code code1">x.y.z-SNAPSHOT</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:77"></span>. Snapshot releases go into a separate directory on Maven Central, and version numbers do not need to be incremented or changed for each snapshot release (instead, the next release version number should be used, with <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:77"></span><code class="code code1">-SNAPSHOT</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:77"></span> appended). These releases can be made as frequently as desired, and users understand that they may be alpha or beta quality. They can be released automatically as part of a CI/CD process. Users of snapshot releases have to opt-in to using the snapshots repository by explicitly referencing it from their own Maven pom.xml file.
|
||||
</p>
|
||||
<div id="java-preview-qualifer-required" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:79">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span><a class='req-label' href='#java-preview-qualifer-required'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span> have a qualifier of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span><code class="code code1">-SNAPSHOT</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:80"></span>, with no additional version number appended to the end of this.</p></div>
|
||||
<div id="java-preview-version-next-ga" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:83">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span><a class='req-label' href='#java-preview-version-next-ga'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span> have the version number represent the version intended for the next GA release. For example, a preview release of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span><code class="code code1">1.0.2-SNAPSHOT</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:84"></span> should be read to mean that it is a snapshot release of version 1.0.2, and that this snapshot will ultimately be superceded by the GA release of 1.0.2 when it becomes available.</p></div><h4 id="sec-preview-releases" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:87" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:87"></span><span class="heading-before"><span class="heading-label">8.3.3</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:87"></span>Preview Releases</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span>Preview releases are made when code hits certain milestones and wider community adoption and testing is warranted. Preview releases replace the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span><code class="code code1">-SNAPSHOT</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span> qualifier with either an <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span><code class="code code1">-alpha</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span>, <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span><code class="code code1">-beta</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span>, or <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span><code class="code code1">-rc</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:89"></span> (release candidate) qualifier, depending on the maturity of the code being released. Preview releases must be made through the engineering systems pipeline.
|
||||
</p>
|
||||
<div id="java-preview-qualifer-required" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:91">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span><a class='req-label' href='#java-preview-qualifer-required'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span> have a qualifier of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span><code class="code code1">-alpha</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span>, <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span><code class="code code1">-beta</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span>, or <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span><code class="code code1">-rc</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:92"></span> for all preview releases.</p></div>
|
||||
<div id="java-preview-qualifier-numbering" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:95">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span><a class='req-label' href='#java-preview-qualifier-numbering'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span> have an incrementing number appended directly to the end of the preview qualifier. For example, <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span><code class="code code1">-beta1</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span>, <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span><code class="code code1">-beta2</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:96"></span>, etc.</p></div>
|
||||
<div id="java-preview-version-next-ga" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:99">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span><a class='req-label' href='#java-preview-version-next-ga'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span> have the version number represent the version intended for the next GA release. For example, a preview release of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span><code class="code code1">1.0.2-beta2</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:100"></span> should be read to mean that it is the second beta release of version 1.0.2, and that this release will be superceded by the GA release of 1.0.2 when it becomes available.</p></div><h4 id="sec-ga-releases" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:103" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:103"></span><span class="heading-before"><span class="heading-label">8.3.4</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:103"></span>GA Releases</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:105"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:105"></span>Anything that is not a snapshot or preview release should be considered an official GA release. Official releases must be done only once per version increment, and must only be done through the engineering system pipeline.
|
||||
</p>
|
||||
<div id="java-use-deprecated-for-retiring-api" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:107">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span><a class='req-label' href='#java-use-deprecated-for-retiring-api'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span> use the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span><code class="code code1">@Deprecated</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span> annotation and the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span><code class="code code1">@deprecated</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:108"></span> JavaDoc tag when a feature is to be removed in a future major release. Explain what is being removed, and how developers should transition to new API.</p></div>
|
||||
<div id="java-deprecation-discuss-before-removal" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:111">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span><a class='req-label' href='#java-deprecation-discuss-before-removal'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span> discuss all deprecations and deprecation-removals with the<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span> <a href="mailto:adparch@microsoft.com">Java architect</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span>. No API should be broken after a GA release without<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span> <a href="mailto:adparch@microsoft.com">Java architect</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:112"></span> approval.</p></div>
|
||||
<div id="java-do-not-change-api-in-non-major-release" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:115">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"></span><a class='req-label' href='#java-do-not-change-api-in-non-major-release'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:116"></span> remove or change API in any patch or minor release. All API changes must occur in conjunction with a major version increment.</p></div>
|
||||
<div id="java-must-indicate-deprecation-before-change" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:119">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"></span><a class='req-label' href='#java-must-indicate-deprecation-before-change'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:120"></span> remove or change API until there has been at least one GA release that contains the deprecation notices in the code. This enables developers to receive deprecation warnings at build time in their development projects.</p></div>
|
||||
<div id="java-no-qualifier-in-ga" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:123">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"></span><a class='req-label' href='#java-no-qualifier-in-ga'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:124"></span> release any SDK component as GA with a snapshot or preview release qualifier.</p></div><h3 id="sec-naming" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:127" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:127"></span><span class="heading-before"><span class="heading-label">8.4</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:127"></span>Naming</h3>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:129"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:129"></span>To make understanding our Azure SDK simpler, it is important that we apply a consistent naming policy across all SDK components. There are a few aspects to this: Java package names, as well as our <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:129"></span><code class="code code1">groupId</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:129"></span> and <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:129"></span><code class="code code1">artifactId</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:129"></span> names for use in our Maven pom.xml file.
|
||||
</p><h4 id="sec-determing-group-and-service-name" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:131" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:131"></span><span class="heading-before"><span class="heading-label">8.4.1</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:131"></span>Determing Group and Service Name</h4>
|
||||
<div class="todo note" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:133" style="display:block">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:134"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:134"></span><a class='req-label' href='#'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:134"></span>✏️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:134"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:134"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:135"></span>Refer reader to external document that details how to determine which group and service name an SDK component should use.</p></div><h4 id="sec-java-package-naming" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:137" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:137"></span><span class="heading-before"><span class="heading-label">8.4.2</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:137"></span>Java Package Naming</h4>
|
||||
<div id="java-consistent-package-naming" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:139">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><a class='req-label' href='#java-consistent-package-naming'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span> use the package naming pattern of all lowercase letters (no camel case is allowed), without spaces, hyphens, or underscores. For example, Azure Key Vault would be in <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><code class="code code1">com.azure.<group>.keyvault</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>- note that the two words <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>‘Key’<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span> and <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>‘Vault’<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span> are brought together to <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><code class="code code1">keyvault</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>, instead of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><code class="code code1">keyVault</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>, <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><code class="code code1">key_vault</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>, or <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span><code class="code code1">key-vault</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:140"></span>.</p></div>
|
||||
<div id="java-consistent-package-structure" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:143">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span><a class='req-label' href='#java-consistent-package-structure'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span> ensure that all code for an SDK component resides in a package which takes the form <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span><code class="code code1">com.azure.<group>.<service>[.<feature>]</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:144"></span>. Sub-packages for various features of the SDK component are fine, and can be named as appropriate.</p></div>
|
||||
<div id="java-do-not-leak-impl" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:147">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"></span><a class='req-label' href='#java-do-not-leak-impl'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:148"></span> allow implementation code (i.e. code that does not form part of the public API) to be mistaken as public API. There are two valid arrangements for implementation code, one (or both) of which must be followed:
|
||||
</p>
|
||||
<ol class="ol compact" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:150">
|
||||
<li class="li ol-li compact-li" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:150"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:150"></span>Implementation classes can be placed within a subpackage named <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:150"></span><code class="code code1">implementation</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:150"></span>.
|
||||
</li>
|
||||
<li class="li ol-li compact-li" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:151"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:151"></span>Implementation classes can be made package-private and placed within the same package as the consuming class.</li></ol></div><h3 id="sec-maven" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:154" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:154"></span><span class="heading-before"><span class="heading-label">8.5</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:154"></span>Maven</h3>
|
||||
<div id="java-maven-use-parent-pom" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:156">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"></span><a class='req-label' href='#java-maven-use-parent-pom'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:157"></span> explicitly specify the Azure Java SDK parent POM file for all SDK components. This enables centralized dependency and build tool management.</p></div>
|
||||
<div id="java-maven-groupid" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:160">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span><a class='req-label' href='#java-maven-groupid'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span> specify the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span><code class="code code1">groupId</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span> as <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span><code class="code code1">com.azure</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:161"></span>.</p></div>
|
||||
<div id="java-maven-artifactid" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:164">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><a class='req-label' href='#java-maven-artifactid'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span> specify the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><code class="code code1">artifactId</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span> to be of the form <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><code class="code code1">azure-<group>-<service></code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span>, for example, <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><code class="code code1">azure-storage-blob</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span>. In cases where the SDK component has multiple children modules, it is acceptable for the root pom.xml <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><code class="code code1">artifactId</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span> to be of the form <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span><code class="code code1">azure-<group>-<service>-parent</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:165"></span>.</p></div>
|
||||
<div id="java-maven-name" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:168">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span><a class='req-label' href='#java-maven-name'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span> specify the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span><code class="code code1">name</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span> element to take the form <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span><code class="code code1">Microsoft Azure SDK component for <service name></code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:169"></span>.</p></div>
|
||||
<div id="java-maven-description" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:172">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span><a class='req-label' href='#java-maven-description'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span> specify the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span><code class="code code1">description</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span> element to be a slightly longer statement along the lines of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span><code class="code code1">This package contains the Microsoft Azure <service> SDK component</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:173"></span>.</p></div>
|
||||
<div id="java-maven-url" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:176">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span><a class='req-label' href='#java-maven-url'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span> specify the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span><code class="code code1">url</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span> element to point to the root of the GitHub repository containing this source code, which will be frequently (although not always or required to be) present at <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span><code class="code code1">https://github.com/Azure/azure-sdk-for-java</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:177"></span>.</p></div>
|
||||
<div id="java-maven-scm" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:180">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"></span><a class='req-label' href='#java-maven-scm'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:181"></span> specify the source code management section, to specify where the source code resides for the SDK component. If the source code is located in the https://github.com/Azure/azure-sdk-for-java repository, then the following form must be used:
|
||||
</p>
|
||||
<pre class="para-block pre-fenced pre-fenced3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:183" data-line-first="425;./docs/design/common/../java/DesignGuidelines.mdk:184" style="display:block"><code data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:184"><scm>
|
||||
<url>scm:git:https://github.com/Azure/azure-sdk-for-java</url>
|
||||
<connection>scm:git:git@github.com:Azure/azure-sdk-for-java.git</connection>
|
||||
<tag>HEAD</tag>
|
||||
</scm></code></pre>
|
||||
<p class="p noindent para-continued" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:191"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:191"></span>In cases where the repository storing the code for the SDK component is different, substitute as necessary to ensure the correct details are provided.</p></div>
|
||||
<div id="java-maven-developers" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:194">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><a class='req-label' href='#java-maven-developers'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> change the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><code class="code code1">developers</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> section of the pom.xml file<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span>- it must only list a developer <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><code class="code code1">id</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><code class="code code1">microsoft</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> and a <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><code class="code code1">name</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span> of <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span><code class="code code1">Microsoft Corporation</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:195"></span>.</p></div>
|
||||
<div id="java-maven-developers-no-one-else" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:198">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"></span><a class='req-label' href='#java-maven-developers-no-one-else'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:199"></span> include additional names to represent the developers involved in the project.</p></div><h3 id="sec-dependencies" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:202" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:202"></span><span class="heading-before"><span class="heading-label">8.6</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:202"></span>Dependencies</h3>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:204"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:204"></span>A separate document is maintained for tracking<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:204"></span> <a href="https://github.com/Azure/azure-sdk/blob/master/docs/design/java/Dependencies.md">permitted Java dependencies</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:204"></span>, and explaining how to add new, or upgrade existing, dependencies. All developers should familiarise themselves with this document.
|
||||
</p>
|
||||
<div id="java-no-new-dependencies" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:206">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span><a class='req-label' href='#java-no-new-dependencies'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span> introduce new dependencies on third party libraries that are already referenced from the parent POM, without first seeking permission from the<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span> <a href="mailto:adparch@microsoft.com">Java architect</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:207"></span>.</p></div>
|
||||
<div id="java-no-dependency-version-overrides" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:210">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span><a class='req-label' href='#java-no-dependency-version-overrides'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span> specify or change dependency versions in your SDK component pom.xml file. All dependency versioning must be centralized through the common parent POM (refer to the<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span> <a href="https://github.com/Azure/azure-sdk/blob/master/docs/design/java/Dependencies.md">dependencies document</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:211"></span> for more details).</p></div><h3 id="sec-coding-conventions" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:214" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:214"></span><span class="heading-before"><span class="heading-label">8.7</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:214"></span>Coding Conventions</h3>
|
||||
<div id="java-be-idiomatic" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:216">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"></span><a class='req-label' href='#java-be-idiomatic'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:217"></span> ensure that all APIs are idiomatic for Java developers and follow best practices.</p></div><h4 id="sec-async" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:220" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:220"></span><span class="heading-before"><span class="heading-label">8.7.1</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:220"></span>Async</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:222"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:222"></span>Due to the nature of internet-based communication, asynchronous APIs are a must to ensure efficient use of system resources (threads and their stacks).
|
||||
</p>
|
||||
<div id="java-async-use-project-reactor" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:224">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span><a class='req-label' href='#java-async-use-project-reactor'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span> use<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span> <a href="http://projectreactor.io">Project Reactor</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:225"></span> to provide end-users with a high-quality async API.</p></div>
|
||||
<div id="java-async-no-other-libs" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:228">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span><a class='req-label' href='#java-async-no-other-libs'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span> use any other approaches, such as <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span><code class="code code1">CompletableFuture</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span> and<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span> <a href="https://github.com/ReactiveX/RxJava">RxJava</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:229"></span>.</p></div>
|
||||
<div id="java-async-no-sync-methods" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:232">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span><a class='req-label' href='#java-async-no-sync-methods'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span> provide synchronous methods in addition to async methods<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:233"></span>- instead follow the policy that developers may choose to block on an asynchronous calls.</p></div>
|
||||
<div id="java-no-async-naming-pattern" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:236">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span><a class='req-label' href='#java-no-async-naming-pattern'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span> use the suffix <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span><code class="code code1">Async</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:237"></span> in methods that perform operations asynchronously. Instead, simply drop the suffix entirely (as all APIs should be async by default, it is a redundant piece of information).</p></div>
|
||||
<div id="java-async-no-overloads" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:240">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"></span><a class='req-label' href='#java-async-no-overloads'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:241"></span> provide multiple asynchronous methods for a single REST endpoint, unless to provide overloaded methods to enable alternative or optional method parameters.</p></div>
|
||||
<div id="java-async-useful-return-type" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:244">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"></span><a class='req-label' href='#java-async-useful-return-type'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:245"></span> ensure that all Async methods return a type that contains all information to enable a developer to inspect the metadata related to the service call (e.g. for HTTP endpoints, the async method call must return a type that enables the developer to read the headers, status code, and all other useful information).</p></div>
|
||||
<div id="java-async-no-custom-api" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:248">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span><a class='req-label' href='#java-async-no-custom-api'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span> write custom APIs for streaming or async operations<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span>- make use of the existing functionality offered in the Azure Java SDK base class library. Where necessary, additional functionality should be introduced into the Azure Java SDK base class library after discussions with the<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span> <a href="mailto:adparch@microsoft.com">Java architect</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:249"></span>.</p></div>
|
||||
<div id="java-async-no-blocking" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:252">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span><a class='req-label' href='#java-async-no-blocking'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span> include blocking calls inside SDK component code. Code must be async throughout entire codebase. Use<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span> <a href="https://github.com/reactor/BlockHound">BlockHound</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:253"></span> to detect blocking calls in async APIs.</p></div><h4 id="sec-pipelines" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:256" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:256"></span><span class="heading-before"><span class="heading-label">8.7.2</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:256"></span>Pipelines</h4>
|
||||
<div id="java-pipelines-use-existing-api" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:258">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"></span><a class='req-label' href='#java-pipelines-use-existing-api'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:259"></span> use the existing pipelines APIs for all requests to Azure services, including any requirements for authentication, telemetry, logging, tracing, retries, cancellations, etc. Do not use other HTTP clients or means of connecting to Azure services.</p></div>
|
||||
<div class="todo note" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:262" style="display:block">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:263"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:263"></span><a class='req-label' href='#'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:263"></span>✏️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:263"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:263"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:264"></span>Refer back to general guidelines doc.</p></div><h4 id="sec-logging" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:266" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:266"></span><span class="heading-before"><span class="heading-label">8.7.3</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:266"></span>Logging</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:268"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:268"></span>Logging is critical to provide developers insight into why things are operating the way they are, and to help diagnose issues that are preventing their successful use of our SDK.
|
||||
</p>
|
||||
<div id="java-logging-use-slf4j" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:270">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span><a class='req-label' href='#java-logging-use-slf4j'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span> use the APIs provided by the<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span> <a href="https://www.slf4j.org/">SLF4J</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span> project, as this is the only logging API to be used in all Azure Java SDK components. Refer to the<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span> <a href="https://www.slf4j.org/manual.html">SLF4J user manual</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:271"></span> for additional guidance.</p></div><h4 id="sec-tooling" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:274" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:274"></span><span class="heading-before"><span class="heading-label">8.7.4</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:274"></span>Tooling</h4><h5 id="sec-spotbugs" class="h4" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:276" data-heading-depth="4" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:276"></span>SpotBugs</h5>
|
||||
<div id="java-tooling-code-linter" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:278">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span><a class='req-label' href='#java-tooling-code-linter'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span> run SpotBugs using the centralised Azure SDK SpotBugs rule set. As all projects must have a Maven inheritance hierarchy that includes the Azure SDK Maven pom.xml, this is configured automatically, and the tooling will execute by calling <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span><code class="code code1">mvn spotbugs:spotbugs</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:279"></span>. It will also execute as part of the build process, failing the build if any SpotBugs issue is found.</p></div>
|
||||
<div id="java-tooling-code-linter-test-no-commit-on-failure" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:282">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span><a class='req-label' href='#java-tooling-code-linter-test-no-commit-on-failure'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span> push code to a repo that breaks SpotBugs. Because the build is set to fail if any SpotBugs issue is found, it should always be a case that the build can complete successfully before any code is committed and pushed. If a build fails, a SpotBugs HTML report can be generated by calling <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span><code class="code code1">mvn spotbugs:spotbugs</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:283"></span> on the command line. This report will provide context about the failure and point the developer towards fixing it.</p></div>
|
||||
<div class="todo note" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:286" style="display:block">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:287"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:287"></span><a class='req-label' href='#'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:287"></span>✏️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:287"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:287"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:288"></span>Provide details on configuring IDEs to use the Microsoft-specified SpotBugs rule set.</p></div><h5 id="sec-checkstyle" class="h4" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:290" data-heading-depth="4" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:290"></span>CheckStyle</h5>
|
||||
<div id="java-tooling-code-style" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:292">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span><a class='req-label' href='#java-tooling-code-style'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span> run CheckStyle, in a similar fashion to SpotBugs above. All relevant rules will be run on each build. Whilst CheckStyle failures are less critical, all failures must be resolved prior to a GA release. If a build fails, a CheckStyle HTML report can be generated by calling <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span><code class="code code1">mvn checkstyle:checkstyle</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:293"></span> on the command line. This report will provide context about the failure and point the developer towards fixing it.</p></div>
|
||||
<div class="todo note" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:296" style="display:block">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:297"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:297"></span><a class='req-label' href='#'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:297"></span>✏️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:297"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:297"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:298"></span>Provide details on configuring IDEs to use the Microsoft-specified CheckStyle rule set.</p></div><h5 id="sec-jacoco" class="h4" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:300" data-heading-depth="4" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:300"></span>JaCoCo</h5>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:302"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:302"></span>Unit tests, as covered in the next section, are an important means of ensuring that our code does what we expect it to, and that it continues to do what we expect as the codebase is developed in future releases. Having a sense of how well our codebase is covered in tests is therefore a useful goal, and this is where<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:302"></span> <a href="https://www.eclemma.org/jacoco/">JaCoCo</a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:302"></span> can be useful<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:302"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:302"></span>- it generates HTML reports stating the coverage our unit tests have on the codebase.
|
||||
</p>
|
||||
<div id="java-test-coverage" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:304">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span><a class='req-label' href='#java-test-coverage'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span> ensure that code test coverage is satisfactory by producing a JaCoCo report using <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span><code class="code code1">mvn jacoco:report</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:305"></span>.</p></div><h4 id="sec-testing" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:308" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:308"></span><span class="heading-before"><span class="heading-label">8.7.5</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:308"></span>Testing</h4>
|
||||
<div id="java-testing-complete" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:310">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"></span><a class='req-label' href='#java-testing-complete'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:311"></span> ensure that the unit tests cover important code paths and that all branches in these code paths are tested comprehensively.</p></div>
|
||||
<div id="java-testing-have-mock-and-live-tests" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:314">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span><a class='req-label' href='#java-testing-have-mock-and-live-tests'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span> have a mock test suite testing functionality at a higher level, in addition to unit tests. Mock tests may also support running <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span>‘live’<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:315"></span> against real Azure services. Mock tests can be written as long-form unit tests, or else they may be written with other testing / mocking tools, as necessary.</p></div>
|
||||
<div id="java-testing-commit-mocks-to-repo" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:318">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"></span><a class='req-label' href='#java-testing-commit-mocks-to-repo'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:319"></span> provide all necessary mock and live tests as part of the SDK component repository.</p></div>
|
||||
<div id="java-testing-mocks-run-fast" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:322">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"></span><a class='req-label' href='#java-testing-mocks-run-fast'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:323"></span> ensure that all mock tests execute quickly and are integrated into the main unit test suite.</p></div>
|
||||
<div id="java-testing-mocks-give-exec-instructions" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:326">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span><a class='req-label' href='#java-testing-mocks-give-exec-instructions'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span> provide instructions as part of your Contributing.<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span><span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span></span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span>md file to detail how to execute these tests (if different than calling <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span><code class="code code1">mvn test</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:327"></span>), including any environment variables, running services, etc. Test that these instructions are complete by attempting to run the tests on a separate machine.</p></div><h3 id="sec-documentation" class="h2" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:330" data-heading-depth="2" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:330"></span><span class="heading-before"><span class="heading-label">8.8</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:330"></span>Documentation</h3>
|
||||
<div id="java-maven-no-dependency-versions-in-docs" class="mustnot" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:332">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"></span><a class='req-label' href='#java-maven-no-dependency-versions-in-docs'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"></span>⛔️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"></span><strong class="strong-star2">DO NOT</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:333"></span> include version details when specifying Maven dependency statements. Always refer the user back to a central document detailing how to use the Azure SDK for Java BOM.</p></div>
|
||||
<div class="todo note" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:336" style="display:block">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:337"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:337"></span><a class='req-label' href='#'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:337"></span>✏️<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:337"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:337"></span><span class="note-before"><strong class="strong-star2"><span class="note-caption">Todo</span></strong>.
|
||||
</span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:338"></span>Link to central document detailing Azure SDK BOM.</p></div><h4 id="sec-code-samples" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:340" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:340"></span><span class="heading-before"><span class="heading-label">8.8.1</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:340"></span>Code Samples</h4>
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:342"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:342"></span>Code samples are small applications that demonstrate a certain feature that is relevant to the SDK component, allowing developers to more quickly understand the full usage requirements of a particular set of API. Code samples should not be any more complex than they need to be to demonstrate this feature<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:342"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:342"></span>- they should not become full applications. At all times code samples should have a very high signal:noise ratio between useful code and boilerplate code for non-related reasons.
|
||||
</p>
|
||||
<div id="java-samples-location" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:344">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span><a class='req-label' href='#java-samples-location'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span> place code samples within the <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span><code class="code code1">/src/samples/java</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:345"></span> directory within the SDK component root directory. This ensures that the code will be compiled, but not packaged into the resulting jar.</p></div>
|
||||
<div id="java-samples-execution" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:348">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span><a class='req-label' href='#java-samples-execution'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span> ensure that each sample file is executable by including a <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span><code class="code code1">public static void main(String[] args)</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:349"></span> method.</p></div>
|
||||
<div id="java-samples-use-latest-conventions" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:352">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span><a class='req-label' href='#java-samples-use-latest-conventions'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span> use the latest coding conventions when creating samples. It is recommended to make liberal use of modern Java syntax and API such as diamond operators, etc as they remove boilerplate from your samples and let your library<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span>'<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:353"></span>s API shine through better. Do not use any language feature or API of Java beyond the current Java baseline versioned employed by the SDK, currently this is JDK 8.</p></div>
|
||||
<div id="java-samples-maintained" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:356">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span><a class='req-label' href='#java-samples-maintained'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span> keep sample code maintained and using the latest major release of the library. Sample code repos must be reviewed for freshness and at least one commit must be made to a sample repo every semester<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:357"></span>- at least to update dependencies to the latest release and to ensure that the code continues to function as expected.</p></div>
|
||||
<div id="java-samples-easy-grafting" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:360">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"></span><a class='req-label' href='#java-samples-easy-grafting'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:361"></span> ensure that sample code snippets can be easily grafted from the documentation into a users own application and not tied to variable declarations not covered in previous snippets in the content.</p></div>
|
||||
<div id="java-samples-keep-simple" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:364">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"></span><a class='req-label' href='#java-samples-keep-simple'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:365"></span> ensure that code snippets are optimized for ease of reading and comprehension over code compactness and efficiency unless the article context demands otherwise.</p></div>
|
||||
<div id="java-samples-cross-platform" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:368">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"></span><a class='req-label' href='#java-samples-cross-platform'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:369"></span> ensure that samples can run in Windows, macOS, and Linux development environments, and are not tied to a non-standard developer toolchain.</p></div><h4 id="sec-javadoc" class="h3" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:372" data-heading-depth="3" style="display:block"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:372"></span><span class="heading-before"><span class="heading-label">8.8.2</span>. </span><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:372"></span>JavaDoc</h4>
|
||||
<div id="java-javadoc-easy-generation" class="must" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:374">
|
||||
<p class="p noindent" data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span><a class='req-label' href='#java-javadoc-easy-generation'><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span>✅<span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span></a><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span> <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span><strong class="strong-star2">DO</strong><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span> ensure that anybody can clone the repo containing the SDK component and execute <span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span><code class="code code1">mvn javadoc:javadoc</code><span data-line="425;./docs/design/common/../java/DesignGuidelines.mdk:375"></span> to generate the full and complete JavaDoc output for the code, without any need for additional processing steps.</p></div><h2 id="sec-python-specific-guidelines" class="h1" data-line="427" data-heading-depth="1" style="display:block"><span data-line="427"></span><span class="heading-before"><span class="heading-label">9</span>. </span><span data-line="427"></span>Python Specific Guidelines</h2><h2 id="sec-javascript-specific-guidelines" class="h1" data-line="429" data-heading-depth="1" style="display:block"><span data-line="429"></span><span class="heading-before"><span class="heading-label">10</span>. </span><span data-line="429"></span>JavaScript Specific Guidelines</h2><h2 id="sec-go-specific-guidelines" class="h1" data-line="431" data-heading-depth="1" style="display:block"><span data-line="431"></span><span class="heading-before"><span class="heading-label">11</span>. </span><span data-line="431"></span>Go Specific Guidelines</h2><span data-line=""></span></div>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
318
out/ellipse.sty
318
out/ellipse.sty
|
|
@ -1,318 +0,0 @@
|
|||
%%
|
||||
%% This is file `ellipse.sty',
|
||||
%% generated with the docstrip utility.
|
||||
%%
|
||||
%% The original source files were:
|
||||
%%
|
||||
%% ellipse.dtx (with options: `package')
|
||||
%%
|
||||
%% Copyright (C) 2015
|
||||
%% Daan Leijen
|
||||
%%
|
||||
%% This work may be distributed and/or modified under the
|
||||
%% conditions of the LaTeX Project Public License, either version 1.3
|
||||
%% of this license or (at your option) any later version.
|
||||
%% The latest version of this license is in
|
||||
%% http://www.latex-project.org/lppl.txt
|
||||
%% and version 1.3 or later is part of all distributions of LaTeX
|
||||
%% version 2003/12/01 or later.
|
||||
%%
|
||||
%% This work has the LPPL maintenance status "author-maintained".
|
||||
%%
|
||||
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
|
||||
\ProvidesPackage{ellipse}
|
||||
[2004/11/05 v1.0 .dtx ellipse file]
|
||||
\RequirePackage{pict2e}
|
||||
|
||||
\providecommand*\pIIe@csedef[1]{\expandafter\edef\csname #1\endcsname}
|
||||
\newcommand*\pIIe@ellip@csqrt[3]{%
|
||||
\@ovxx=#1\relax
|
||||
\ifdim\@ovxx<\z@\@ovxx-\@ovxx\fi
|
||||
\@ovyy=#2\relax
|
||||
\ifdim\@ovyy<\z@\@ovyy-\@ovyy\fi
|
||||
\edef\pIIe@csname{@csqrt(\number\@ovxx,\number\@ovyy)}%
|
||||
\expandafter\ifx\csname\pIIe@csname\endcsname\relax
|
||||
\pIIe@ellip@csqrt@%
|
||||
\pIIe@csedef{\pIIe@csname}{\the\dimen@}%
|
||||
#3\dimen@
|
||||
\else
|
||||
#3\dimexpr\csname\pIIe@csname\endcsname\relax
|
||||
\fi
|
||||
}
|
||||
\newcommand*\pIIe@ellip@csqrt@{%
|
||||
\@ovdx\@ovxx
|
||||
\advance\@ovdx by \@ovyy
|
||||
\dimen@0.7071067\@ovdx
|
||||
\ifdim\dimen@<\@ovyy\dimen@\@ovyy\fi
|
||||
\ifdim\dimen@<\@ovxx\dimen@\@ovxx\fi
|
||||
\ifdim\@ovdx<128\p@
|
||||
\edef\@tempa{\strip@pt\@ovxx}%
|
||||
\@ovxx\@tempa\@ovxx
|
||||
\edef\@tempa{\strip@pt\@ovyy}%
|
||||
\@ovyy\@tempa\@ovyy
|
||||
\advance\@ovxx by \@ovyy
|
||||
\advance\dimen@ by \dimexpr1pt * \@ovxx/\dimen@\relax
|
||||
\divide\dimen@ by 2%
|
||||
\advance\dimen@ by \dimexpr1pt * \@ovxx/\dimen@\relax
|
||||
\divide\dimen@ by 2%
|
||||
\fi
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@atan@{%
|
||||
\@tempdima\dimen@
|
||||
\@tempdimb\@tempdima
|
||||
\ifdim\@tempdimb<\z@\@tempdimb-\@tempdimb\fi
|
||||
\dimen@0.0663\@tempdimb
|
||||
\advance\dimen@ 0.2447pt\relax
|
||||
\advance\@tempdimb -1pt\relax
|
||||
\edef\@tempa{\strip@pt\@tempdimb}%
|
||||
\dimen@\@tempa\dimen@
|
||||
\edef\@tempa{\strip@pt\@tempdima}%
|
||||
\dimen@\@tempa\dimen@
|
||||
\dimen@-\dimen@
|
||||
\advance\dimen@ 0.7853\@tempdima
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@atantwo[3]{%
|
||||
\edef\pIIe@csname{@atan2(\number\dimexpr#1\relax,\number\dimexpr#2\relax)}%
|
||||
\expandafter\ifx\csname\pIIe@csname\endcsname\relax
|
||||
\pIIe@atantwo@{#1}{#2}{#3}%
|
||||
\pIIe@csedef{\pIIe@csname}{\the\dimexpr#3\relax}%
|
||||
\else
|
||||
#3\dimexpr\csname\pIIe@csname\endcsname\relax
|
||||
\fi
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@atantwo@[3]{%
|
||||
\@tempdima\dimexpr#2\relax
|
||||
\@tempdimb\dimexpr#1\relax
|
||||
\ifdim\@tempdima=\z@\relax
|
||||
\ifdim\@tempdimb>\z@\relax\dimen@90\p@
|
||||
\else\ifdim\@tempdimb<\z@\relax\dimen@-90\p@
|
||||
\else\dimen@0\p@
|
||||
\fi\fi
|
||||
\else
|
||||
\@tempdimd\z@
|
||||
\ifdim\@tempdima<\z@\relax
|
||||
\ifdim\@tempdimb<\z@\relax\@tempdimd-180\p@
|
||||
\else\@tempdimd180\p@
|
||||
\fi
|
||||
\fi
|
||||
\dimen@\dimexpr1pt * \@tempdimb/\@tempdima\relax
|
||||
\@tempdimc\dimen@
|
||||
\ifdim\@tempdimc<\z@\relax\@tempdimc-\@tempdimc\fi
|
||||
\ifdim\@tempdimc>\p@\relax
|
||||
\dimen@\dimexpr1pt * \@tempdima/\@tempdimb\relax
|
||||
\ifdim\dimen@<\z@\relax\def\@tempsign{-}\else\def\@tempsign{}\fi
|
||||
\pIIe@atan@
|
||||
\dimen@-\dimen@
|
||||
\advance\dimen@ by \@tempsign1.5707pt\relax
|
||||
\else
|
||||
\pIIe@atan@
|
||||
\fi
|
||||
\dimen@57.29578\dimen@
|
||||
\advance\dimen@ by \@tempdimd
|
||||
\fi
|
||||
#3\dimen@%
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@noneto[2]{}
|
||||
\newcommand*\pIIe@ellip@sincost@[2]{%
|
||||
\CalculateSin{#1}%
|
||||
\CalculateCos{#1}%
|
||||
\@tempdima\UseSin{#1}\p@
|
||||
\@tempdimb\UseCos{#1}\p@
|
||||
\ifdim\@tempdima=\p@\relax
|
||||
\pIIe@csedef{@ellipsin#2}{1}%
|
||||
\pIIe@csedef{@ellipcos#2}{0}%
|
||||
\else\ifdim\@tempdima=-\p@\relax
|
||||
\pIIe@csedef{@ellipsin#2}{-1}%
|
||||
\pIIe@csedef{@ellipcos#2}{0}%
|
||||
\else
|
||||
\@tempdimc\@ellipratio\dimexpr1pt * \@tempdima/\@tempdimb\relax
|
||||
%\typeout{ i#2=\the\@tempdimc, sin(#1)=\the\@tempdima}%
|
||||
\pIIe@ellip@csqrt{\p@}{\@tempdimc}\@tempdimd
|
||||
\ifdim\@tempdimb<\z@\relax\@tempdimd-\@tempdimd\fi
|
||||
\pIIe@csedef{@ellipsin#2}{\strip@pt\dimexpr1pt * \@tempdimc/\@tempdimd\relax}%
|
||||
\pIIe@csedef{@ellipcos#2}{\strip@pt\dimexpr1pt * \p@/\@tempdimd\relax}%
|
||||
\fi\fi
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@ellip@sincost[2]{%
|
||||
%\typeout{ calc sin cos: angles (#1,#2), radii: (\the\@ovro,\the\@ovri)}%
|
||||
\edef\@ellipratio{\strip@pt\dimexpr1pt * \@ovro/\@ovri\relax}%
|
||||
\pIIe@ellip@sincost@{#1}{one}%
|
||||
\pIIe@ellip@sincost@{#2}{two}%
|
||||
%\typeout{ sincos(a=#1)=(\@ellipsinone,\@ellipcosone), sincos(a=#2)=(\@ellipsintwo,\@ellipcostwo), }%
|
||||
}
|
||||
\newcommand*\pIIe@omega[3]{%
|
||||
\@tempdima\csname @ellipcos#3\endcsname\@ovro
|
||||
\advance\@tempdima by #1\relax
|
||||
\@tempdimb\csname @ellipsin#3\endcsname\@ovri
|
||||
\advance\@tempdimb by #2\relax
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@omegai[1]{%
|
||||
\@tempdimc\csname @ellipsin#1\endcsname\@ovro
|
||||
\@tempdimc-\@tempdimc
|
||||
\@tempdimd\csname @ellipcos#1\endcsname\@ovri
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@ellip@kappa{%
|
||||
\@ovyy\@ellipsinone\p@
|
||||
\@ovxx\@ellipcosone\p@
|
||||
\@tempdima\@ellipcostwo\@ovyy
|
||||
\@tempdima-\@tempdima
|
||||
\advance\@tempdima by \@ellipsintwo\@ovxx
|
||||
\@tempdimb\@ellipcostwo\@ovxx
|
||||
\advance\@tempdimb by \@ellipsintwo\@ovyy
|
||||
\ifdim\@tempdima=\z@\relax
|
||||
\edef\@ellipkappa{0}%
|
||||
\else
|
||||
\dimen@\dimexpr1pt - \@tempdimb\relax
|
||||
\dimen@\dimexpr1pt * \dimen@/\@tempdima\relax
|
||||
\pIIe@ellip@csqrt{2\p@}{1.73205\dimen@}{\dimen@}%
|
||||
\advance\dimen@ by -\p@
|
||||
\divide\dimen@ by 3%
|
||||
\edef\@tempa{\strip@pt\@tempdima}%
|
||||
\dimen@\@tempa\dimen@
|
||||
\edef\@ellipkappa{\strip@pt\dimen@}%
|
||||
\fi
|
||||
%\typeout{ calculated kappa: \@ellipkappa}%
|
||||
}
|
||||
|
||||
\newcommand*\pIIe@elliparc@[5]{%
|
||||
%\typeout{elliparc: #1, center: (#2, #3), radius (\the\@ovro, \the\@ovri),angle (#4, #5)}%
|
||||
\ifcase #1\relax
|
||||
\let\@ellip@startto\pIIe@lineto
|
||||
\or \let\@ellip@startto\pIIe@moveto
|
||||
\or \let\@ellip@startto\pIIe@noneto%
|
||||
\else\PackageWarning{ellipse}{Illegal initial action in \protect\elliparc: %
|
||||
must be one of 0 (lineto), 1 (moveto) or 2 (do nothing) but I got: #1}%
|
||||
\fi
|
||||
\ifdim\@ovro=\z@\relax\@ovri\z@\fi
|
||||
\ifdim\@ovri=\z@\relax
|
||||
\@ellip@startto{#2}{#3}%
|
||||
\else
|
||||
\pIIe@ellip@sincost{#4}{#5}%
|
||||
\pIIe@elliparc@draw{#2}{#3}%
|
||||
\fi
|
||||
}
|
||||
\newcommand*\pIIe@elliparc@t[5]{%
|
||||
\ifcase #1\relax
|
||||
\let\@ellip@startto\pIIe@lineto
|
||||
\or \let\@ellip@startto\pIIe@moveto
|
||||
\or \let\@ellip@startto\pIIe@noneto%
|
||||
\else\PackageWarning{ellipse}{Illegal initial action in \protect\elliparc: %
|
||||
must be one of 0 (lineto), 1 (moveto) or 2 (do nothing) but I got: #1}%
|
||||
\fi
|
||||
\ifdim\@ovro=\z@\relax\@ovri\z@\fi
|
||||
\ifdim\@ovri=\z@\relax
|
||||
\@ellip@startto{#2}{#3}%
|
||||
\else
|
||||
\CalculateSin{#4}\CalculateCos{#4}%
|
||||
\edef\@ellipsinone{\UseSin{#4}}%
|
||||
\edef\@ellipcosone{\UseCos{#4}}%
|
||||
\CalculateSin{#5}\CalculateCos{#5}%
|
||||
\edef\@ellipsintwo{\UseSin{#5}}%
|
||||
\edef\@ellipcostwo{\UseCos{#5}}%
|
||||
\pIIe@elliparc@draw{#2}{#3}%
|
||||
\fi
|
||||
}
|
||||
\newcommand*\pIIe@elliparc@draw[2]{%
|
||||
\pIIe@ellip@kappa%
|
||||
\pIIe@omega{#1}{#2}{one}%
|
||||
%\typeout{ point one: (\the\@tempdima,\the\@tempdimb)}%
|
||||
\@ellip@startto\@tempdima\@tempdimb
|
||||
\pIIe@omegai{one}%
|
||||
\advance\@tempdima by \@ellipkappa\@tempdimc
|
||||
\advance\@tempdimb by \@ellipkappa\@tempdimd
|
||||
\pIIe@add@nums\@tempdima\@tempdimb
|
||||
%\typeout{ control one: (\the\@tempdima,\the\@tempdimb)}%
|
||||
\pIIe@omega{#1}{#2}{two}%
|
||||
\pIIe@omegai{two}%
|
||||
\@tempdimc\@ellipkappa\@tempdimc
|
||||
\@tempdimd\@ellipkappa\@tempdimd
|
||||
\@tempdimc-\@tempdimc
|
||||
\@tempdimd-\@tempdimd
|
||||
\advance\@tempdimc by \@tempdima
|
||||
\advance\@tempdimd by \@tempdimb
|
||||
\pIIe@add@nums\@tempdimc\@tempdimd
|
||||
%\typeout{ control two: (\the\@tempdimc,\the\@tempdimd)}%
|
||||
\pIIe@add@CP\@tempdima\@tempdimb
|
||||
%\typeout{ point two: (\the\@tempdima,\the\@tempdimb)}%
|
||||
\pIIe@addtoGraph\pIIe@curveto@op
|
||||
}
|
||||
\newcommand*\pIIe@elliparc[7][0]{%
|
||||
\@ovro #4\relax
|
||||
\@ovri #5\relax
|
||||
\iffalse%dim\@ovro=\@ovri
|
||||
\pIIe@arc[#1]{#2}{#3}{#4}{#6}{#7}
|
||||
\else
|
||||
\ifdim \@ovro<\z@ \pIIe@badcircarg\else
|
||||
\ifdim \@ovri<\z@ \pIIe@badcircarg\else
|
||||
\@arclen #7\p@ \advance\@arclen -#6\p@
|
||||
\ifdim \@arclen<\z@ \def\@tempsign{-}\else\def\@tempsign{}\fi
|
||||
\ifdim \@tempsign\@arclen>720\p@
|
||||
\PackageWarning {ellipse}{The arc angle is reduced to -720..720}%
|
||||
\@whiledim \@tempsign\@arclen>720\p@ \do {\advance\@arclen-\@tempsign360\p@}%
|
||||
\@tempdima #6\p@ \advance\@tempdima \@arclen
|
||||
\edef\@angleend{\strip@pt\@tempdima}%
|
||||
\pIIe@@elliparc{#1}{#2}{#3}{#6}{\@angleend}%
|
||||
\else
|
||||
\pIIe@@elliparc{#1}{#2}{#3}{#6}{#7}%
|
||||
\fi
|
||||
\fi
|
||||
\fi
|
||||
\fi
|
||||
}
|
||||
\newcommand*\pIIe@@elliparc[5]{%
|
||||
\begingroup
|
||||
\ifdim \@tempsign\@arclen>90\p@
|
||||
\divide\@arclen 2%
|
||||
\@tempdima #4\p@\advance\@tempdima by \@arclen
|
||||
\edef\@anglemid{\strip@pt\@tempdima}%
|
||||
\def\@tempa{\pIIe@@elliparc{#1}{#2}{#3}{#4}}%
|
||||
\expandafter\@tempa\expandafter{\@anglemid}%
|
||||
\def\@tempa{\pIIe@@elliparc{2}{#2}{#3}}%
|
||||
\expandafter\@tempa\expandafter{\@anglemid}{#5}%
|
||||
\else
|
||||
\pIIe@elliparc@{#1}{#2}{#3}{#4}{#5}%
|
||||
\fi
|
||||
\endgroup
|
||||
}%
|
||||
|
||||
\newcommand*\pIIeelliparc[7][0]{%
|
||||
\@killglue
|
||||
\pIIe@elliparc[#1]{#2\unitlength}{#3\unitlength}{#4\unitlength}{#5\unitlength}{#6}{#7}%
|
||||
\ignorespaces%
|
||||
}
|
||||
\ifx\undefined\elliparc\else
|
||||
\PackageWarning{ellipse}{\protect\elliparc\space is redefined}%
|
||||
\fi
|
||||
\let\elliparc\pIIeelliparc
|
||||
|
||||
\newcommand*\pIIeearc
|
||||
{\@ifstar{\@tempswatrue\pIIe@earc@}{\@tempswafalse\pIIe@earc@}}
|
||||
\newcommand*\pIIe@earc@[3][0,360]{\pIIe@earc@@(#1){#2}{#3}}
|
||||
\def\pIIe@earc@@(#1,#2)#3#4{%
|
||||
\if@tempswa
|
||||
\pIIe@moveto\z@\z@
|
||||
\pIIe@elliparc{\z@}{\z@}{#3\unitlength}{#4\unitlength}{#1}{#2}%
|
||||
\pIIe@closepath\pIIe@fillGraph
|
||||
\else
|
||||
\pIIe@elliparc[1]{\z@}{\z@}{#3\unitlength}{#4\unitlength}{#1}{#2}%
|
||||
\pIIe@strokeGraph
|
||||
\fi}
|
||||
\ifx\undefined\earc\else
|
||||
\PackageWarning{ellipse}{\protect\earc\space is redefined}%
|
||||
\fi
|
||||
\let\earc\pIIeearc
|
||||
|
||||
\newcommand*\pIIeellipse
|
||||
{\@ifstar{\@tempswatrue\pIIe@earc@}{\@tempswafalse\pIIe@earc@}}
|
||||
\let\ellipse\pIIeellipse
|
||||
|
||||
\endinput
|
||||
%%
|
||||
%% End of file `ellipse.sty'.
|
||||
853
out/longbox.sty
853
out/longbox.sty
|
|
@ -1,853 +0,0 @@
|
|||
%---------------------------------------------------------------------------
|
||||
% Copyright 2015 Daan Leijen, Microsoft Corporation.
|
||||
%
|
||||
% This work may be distributed and/or modified under the
|
||||
% conditions of the LaTeX Project Public License, either version 1.3
|
||||
% of this license or (at your option) any later version.
|
||||
% The latest version of this license is in
|
||||
% http://www.latex-project.org/lppl.txt
|
||||
% and version 1.3 or later is part of all distributions of LaTeX
|
||||
% version 2005/12/01 or later.
|
||||
%---------------------------------------------------------------------------
|
||||
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
|
||||
|
||||
\ProvidesPackage{longbox}[2015/12/01, Daan Leijen, Provides basic longbox that can break over pages]
|
||||
\RequirePackage{options}
|
||||
|
||||
\@ifclassloaded{beamer}{%
|
||||
\newcommand\lb@savefootnotes{}%
|
||||
\newcommand\lb@restorefootnotes{}%
|
||||
}%
|
||||
{\RequirePackage{footnote}%
|
||||
\newcommand\lb@savefootnotes{\savenotes}%
|
||||
\newcommand\lb@restorefootnotes{\spewnotes}%
|
||||
}
|
||||
|
||||
|
||||
% --------------------------------------------------------
|
||||
% Debugging
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newcommand*\lb@debug[1]{%
|
||||
\ontoggle{lb@debug}{\typeout{longbox debug: #1}}%
|
||||
}
|
||||
\newcommand*\lb@typeout[1]{%
|
||||
\ontoggle{lb@verbose}{\typeout{longbox: #1}}%
|
||||
}
|
||||
\newcommand*\lb@warncannotsplit{%
|
||||
\PackageWarning{longbox}{Cannot split box; it seems you are using a non-splittable contents}%
|
||||
}
|
||||
\newcommand*\lb@warnbadsplit[1]{%
|
||||
\PackageWarning{longbox}{Bad split (underful vbox by \the#1)}%
|
||||
}
|
||||
|
||||
|
||||
% --------------------------------------------------------
|
||||
% Utilities for LaTeX internals
|
||||
% --------------------------------------------------------
|
||||
|
||||
% Suppress the indentation on the following paragraph
|
||||
\providecommand\nofirstindent{\@afterindentfalse\@afterheading}
|
||||
|
||||
% Suppress the paragraph skip on the following paragraph
|
||||
\providecommand\nofirstparskip{\addvskip{-\parskip}}
|
||||
|
||||
% In contrast to addvspace, addvskip is not suppressed in a minipage
|
||||
\providecommand\addvskip[1]{%
|
||||
\ifvmode
|
||||
\ifdim\lastskip=\z@
|
||||
\vskip #1\relax
|
||||
\else
|
||||
\@tempskipb#1\relax\@xaddvskip
|
||||
\fi
|
||||
\else\@noitemerr\fi
|
||||
}
|
||||
|
||||
|
||||
% Skip to 0.3\baselineskip multiple taking prevdepth into account.
|
||||
\newskip\lb@prevdepth
|
||||
\newcommand\lb@skiptobaseline{%
|
||||
\global\lb@prevdepth=-\@m\p@\relax
|
||||
\ifvmode
|
||||
\ifdim\lastskip=\z@\relax
|
||||
\ifdim\prevdepth=-\@m\p@\else
|
||||
\dimen@\prevdepth
|
||||
% Calculate the modulus of the previous depth with 0.3|\baselineskip| in |\dimen@|.
|
||||
\@tempcnta\prevdepth
|
||||
\@tempskipa=0.3\baselineskip\relax
|
||||
\@tempcntb=\@tempskipa\relax
|
||||
\divide \@tempcnta by \@tempcntb
|
||||
\dimen@\prevdepth
|
||||
\advance\dimen@ -\@tempcnta\@tempskipa
|
||||
% Skip back by that amount, and then skip by 0.3|\baselineskip|.
|
||||
\vskip -\dimen@
|
||||
\vskip \@tempskipa\relax
|
||||
\global\lb@prevdepth=\@tempskipa\relax
|
||||
\fi
|
||||
\fi
|
||||
\fi
|
||||
}
|
||||
|
||||
% unvbox a box, and return a vbox with a given background color
|
||||
% \unvcolorbox{<colorspec>}{<vboxname>}
|
||||
\newcommand\unvcolorbox[2]{%
|
||||
\ifoptionblank{#1}{\vbox{\unvbox#2}}{%
|
||||
\lb@debug{vcolorbox: #1}%
|
||||
\vbox{\offinterlineskip
|
||||
\hbox to \z@{\vbox to \z@{\optioncolor{#1}\hrule\@width\wd#2\@height\ht#2\@depth\dp#2\vss}\hss}%
|
||||
\unvbox#2%
|
||||
}%
|
||||
}%
|
||||
}
|
||||
|
||||
% create a vbox with a given background color
|
||||
\newcommand\vcolorbox[2]{%
|
||||
\eifblank{#1}{\vbox{#2}}{%
|
||||
\setbox\z@=\vbox{#2}\relax
|
||||
\unvcolorbox{#1}{\z@}%
|
||||
}%
|
||||
}%
|
||||
|
||||
% --------------------------------------------------------
|
||||
% The following macros come from mdframed
|
||||
% --------------------------------------------------------
|
||||
|
||||
% Determine the amount of free space left on the current page
|
||||
\newlength\lb@freevspace
|
||||
\newcommand*\lb@setfreevspace@page{%
|
||||
\lb@debug{ determine free space}%
|
||||
\bgroup\@nobreakfalse\addpenalty\z@\egroup%
|
||||
\penalty\@M\relax\vskip 2\baselineskip\relax%
|
||||
\penalty9999\relax\vskip -2\baselineskip\relax%
|
||||
\penalty9999%
|
||||
\ifdim\pagegoal=\maxdimen\relax%
|
||||
\lb@freevspace=\vsize%
|
||||
\else
|
||||
\lb@freevspace=\dimexpr\pagegoal-\pagetotal-\parskip\relax%
|
||||
\fi
|
||||
\lb@debug{free space: \the\lb@freevspace, in page: \the\textheight, vsize=\the\vsize}%
|
||||
}
|
||||
|
||||
\newcommand*\lb@shiftdim[2]{%
|
||||
%\letoption{#1}\lb@list
|
||||
\expandafter\lb@setheadtail@#1,\relax
|
||||
\eifblank{\lb@head}{}{\option@invoke{/longbox/@breakat-previous}{\lb@head}}%
|
||||
#2\option{/longbox/@breakat-previous}%
|
||||
\eifblank{\lb@tail}{}{\let#1\lb@tail}% push back tail
|
||||
}
|
||||
\def\lb@comma{,}%
|
||||
\def\lb@setheadtail@#1,#2\relax{%
|
||||
\def\lb@head{#1}%
|
||||
\def\lb@tail{#2}% adds commas!
|
||||
}
|
||||
|
||||
\newcommand*\lb@setfreevspace{%
|
||||
\eifblank{\lb@breakat}{\lb@setfreevspace@page}{%
|
||||
\def\lb@eject{\par}%no eject
|
||||
\lb@extrasplit=\z@\relax%
|
||||
\lb@shiftdim{\lb@breakat}\lb@freevspace
|
||||
\ifdim\lb@freevspace>\z@\else\lb@setfreevspace@page\fi
|
||||
}%
|
||||
}
|
||||
|
||||
|
||||
% Suppress overfull-underfull vbox messages
|
||||
\newcommand*\lb@ignorevbadness{%
|
||||
\edef\lb@currentvbadness{\the\vbadness}%
|
||||
\edef\lb@currentvfuzz{\the\vfuzz}%
|
||||
\vbadness=\@M\relax%
|
||||
\vfuzz=\maxdimen\relax%
|
||||
\afterassignment\lb@restorevbadness
|
||||
}
|
||||
\newcommand*\lb@restorevbadness{%
|
||||
\vbadness=\lb@currentvbadness\relax
|
||||
\vfuzz=\lb@currentvfuzz\relax
|
||||
}
|
||||
|
||||
|
||||
% --------------------------------------------------------
|
||||
% The 'long vbox' (lvbox) environment collects long material
|
||||
% into a long \vbox, instead of a \hbox like a lrbox in latex.
|
||||
% The collected box can contain any box, minipage, lrbox, fbox etc,
|
||||
% but not outer-par material like a figure. Footnotes can be
|
||||
% dealt with useing lb@savefootnotes.
|
||||
%
|
||||
% The material is typeset in a \vbox according to a given width.
|
||||
% inside the environment, the boolean 'inlvbox' is true.
|
||||
%
|
||||
% \begin{lvbox}{<boxname>}{<width>}
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newif\ifinlvbox
|
||||
\newcommand\lvbox[4]{%
|
||||
\setbox#1\vbox\bgroup
|
||||
\begingroup
|
||||
\inlvboxtrue
|
||||
% reset defaults
|
||||
\let\if@nobreak\iffalse
|
||||
\let\if@noskipsec\iffalse
|
||||
\let\par\@@par
|
||||
\let\-\@dischyph
|
||||
\let\'\@acci\let\`\@accii\let\=\@acciii
|
||||
% set margin and linewidth
|
||||
\leftmargin=#2\relax\rightmargin=#4\relax
|
||||
\@totalleftmargin=\leftmargin%
|
||||
%\leftskip=#2\relax\rightskip=#4\relax\@rightskip=#4\relax
|
||||
\linewidth=#3\relax
|
||||
% set primitive tex margins
|
||||
\leftskip=\@totalleftmargin%
|
||||
\rightskip=\rightmargin%
|
||||
\@rightskip=\rightmargin%
|
||||
\hsize=\dimexpr\@totalleftmargin+\linewidth+\rightmargin\relax
|
||||
\columnwidth\hsize
|
||||
\textwidth\hsize
|
||||
\nofirstindent
|
||||
%\nofirstparskip
|
||||
}
|
||||
\def\endlvbox{\endgroup\egroup}
|
||||
|
||||
|
||||
|
||||
% --------------------------------------------------------
|
||||
%
|
||||
% --------------------------------------------------------
|
||||
|
||||
|
||||
\newsavebox\lb@headbox
|
||||
\newsavebox\lb@savebox
|
||||
\newsavebox\lb@mainbox
|
||||
|
||||
% --------------------------------------------------------
|
||||
%
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newcommand\lb@setbaseline[1]{%
|
||||
%\typeout{ set baseline, \the\dp#1,\the\ht#1}%
|
||||
\ifcase\lb@baseline%
|
||||
\relax%bottom
|
||||
\or%middle
|
||||
\setbox#1=\vbox{\hbox{\lower \dimexpr(\dp#1 + \ht#1)/2 - \dp#1\relax\vbox{\unvbox#1}}}%
|
||||
\or%top
|
||||
\setbox#1=\vtop{\unvbox#1}%
|
||||
\fi
|
||||
%\typeout{ .new dim: \the\dp#1, \the\ht#1}%
|
||||
}
|
||||
|
||||
|
||||
\@ifundefined{define@key}{}%
|
||||
{\define@key{longbox}{options}{\options{#1}\option{/longbox/adjust-options}}}%
|
||||
|
||||
\newcommand*\lb@render@breakbox{%
|
||||
%\typeout{render breakbox entry (in output routine), height=\the\bb@height}%
|
||||
\bb@restorekeys{longbox}%
|
||||
\lb@skiptop=\ifbb@isfirst\option{/longbox/skip-top}\else\option{/longbox/skip-break-top}\fi\relax
|
||||
\lb@skipbottom=\ifbb@islast\option{/longbox/skip-bottom}\else\option{/longbox/skip-break-bottom}\fi\relax
|
||||
\lb@skipbreaktop=\ifbb@isfirst 0pt\else\option{/longbox/skip-break-top}\fi
|
||||
\lb@skipbreakbottom=\ifbb@islast 0pt\else\option{/longbox/skip-break-bottom}\fi
|
||||
%\typeout{ render: skip top=\the\lb@skiptop, bottom=\the\lb@skipbottom, break-top=\the\dimexpr\option{/longbox/skip-bottom}}%
|
||||
\options{%
|
||||
/longbox/@part-height=\bb@height + \lb@skipbreaktop + \lb@skipbreakbottom,
|
||||
/longbox/@part-width=\option{/longbox/width} + \option{/longbox/skip-left} + \option{/longbox/skip-right},%\bb@width,
|
||||
/longbox/@part-depth=0pt,
|
||||
/longbox/@part-needtop=\ifbb@isfirst true\else false\fi,
|
||||
/longbox/@part-needbottom=\ifbb@islast true\else false\fi,
|
||||
/longbox/@content-box-height=\option{/longbox/@part-height} - \lb@skiptop - \lb@skipbottom,
|
||||
/longbox/@content-box-width=\option{/longbox/width},
|
||||
/longbox/@content-box-depth=\option{/longbox/@part-depth},
|
||||
}%
|
||||
%\typeout{breakbox: width=\expandafter\the\option{/longbox/width}, \the\bb@width, \the\dimexpr\option{/longbox/@part-width}}%
|
||||
\vbox{%
|
||||
\kern -\lb@skipbreaktop% todo: move to breakbox?
|
||||
\option{/longbox/render}%
|
||||
\kern -\lb@skipbreakbottom
|
||||
}%
|
||||
}
|
||||
|
||||
\newcommand*\lb@render@vbox[1]{%
|
||||
\lb@debug{render vbox entry}%
|
||||
\lb@restoreoptions
|
||||
\lb@skiptop=\dimexpr\iftoggle{/longbox/@part-needtop}{\option{/longbox/skip-top}}{\option{/longbox/skip-break-top}}\relax
|
||||
\lb@skipbottom=\dimexpr\iftoggle{/longbox/@part-needbottom}{\option{/longbox/skip-bottom}}{\option{/longbox/skip-break-bottom}}\relax
|
||||
%\typeout{ skip top=\the\lb@skiptop, bottom=\the\lb@skipbottom}%
|
||||
% add top skip while maintaining the baseline.
|
||||
\ifdim\lb@skiptop=\z@\relax\else
|
||||
\setbox\z@=\vtop{\unvcopy#1}%
|
||||
\dimen@=\ht\z@
|
||||
\setbox#1=\vbox{\offinterlineskip
|
||||
\hrule width \z@ height \dimexpr\dimen@ + \lb@skiptop\relax depth -\dimen@
|
||||
\unvbox#1%
|
||||
}%
|
||||
\fi
|
||||
% add bottom skip while maintaining the baseline.
|
||||
\ifdim\lb@skipbottom=\z@\relax\else
|
||||
\dimen@=\dp#1%
|
||||
\setbox#1=\vbox{\offinterlineskip\unvbox#1\hrule width \z@ height -\dimen@ depth \dimexpr\dimen@ + \lb@skipbottom\relax}%
|
||||
\fi
|
||||
\lb@setbaseline{#1}%
|
||||
\options{%
|
||||
/longbox/@part-height=\dimexpr\ht#1 + \dp#1\relax,
|
||||
/longbox/@part-width=\dimexpr\wd#1 + \option{/longbox/skip-left} + \option{/longbox/skip-right}\relax,
|
||||
/longbox/@part-depth=\dp#1,
|
||||
/longbox/@content-box-width=\option{/longbox/width},
|
||||
/longbox/@content-box-height=\option{/longbox/@part-height} - \lb@skiptop - \lb@skipbottom,
|
||||
/longbox/@content-box-depth=\option{/longbox/@part-depth} - \lb@skipbottom,
|
||||
}%
|
||||
%\typeout{ longbox: height=\the\dimexpr\option{/longbox/@content-box-height}, outer height=\the\dimexpr\option{/longbox/@part-height}\relax}%
|
||||
% lower the box depending on vertical alignment
|
||||
\ifcase\option{/longbox/vertical-align/@ord}\relax
|
||||
\@tempdima\z@
|
||||
\or
|
||||
%bottom
|
||||
\@tempdima\dimexpr0.3\baselineskip - \option{/longbox/@part-depth}\relax
|
||||
\or%middle
|
||||
\@tempdima\dimexpr0.5\option{/longbox/@part-height} - \option{/longbox/@part-depth}\relax
|
||||
\or%top
|
||||
\@tempdima\dimexpr\option{/longbox/@part-height}-\option{/longbox/@part-depth}-0.7\baselineskip\relax
|
||||
\or%text-bottom
|
||||
\@tempdima\dimexpr0.3\baselineskip - \option{/longbox/@part-depth}\relax
|
||||
\or%text-top
|
||||
\@tempdima\dimexpr\option{/longbox/@part-height}-\option{/longbox/@part-depth}-0.7\baselineskip\relax
|
||||
\or%super
|
||||
\@tempdima=-0.9ex%
|
||||
\or%sub
|
||||
\@tempdima=0.7ex%
|
||||
\else
|
||||
\@tempdima\z@
|
||||
\fi
|
||||
\advance\@tempdima by -\option{/longbox/raise}%
|
||||
\option@invoke{/longbox/@lower}{\@tempdima}%
|
||||
\noindent\hbox{\lower \@tempdima\vbox{\offinterlineskip
|
||||
\hbox to \z@{%
|
||||
\vbox to \z@{%
|
||||
\hbox{\lower \option{/longbox/@part-height}\vbox{\offinterlineskip{\option{/longbox/render}}}}%
|
||||
\vss}%
|
||||
\hss
|
||||
}%
|
||||
\hbox{%
|
||||
\ifdim\option{/longbox/skip-left}=\z@\else\hskip\option{/longbox/skip-left}\fi
|
||||
\box#1%
|
||||
\ifdim\option{/longbox/skip-right}=\z@\else\hskip\option{/longbox/skip-right}\fi
|
||||
%$\box#1%
|
||||
}%
|
||||
}}%
|
||||
}
|
||||
|
||||
\newcommand*\lb@single@[1]{%
|
||||
\begingroup
|
||||
\toggletrue{/longbox/@part-needtop}%
|
||||
\toggletrue{/longbox/@part-needbottom}%
|
||||
\lb@render@vbox{#1}%
|
||||
\endgroup
|
||||
}
|
||||
\newcommand*\lb@first@[1]{%
|
||||
\begingroup
|
||||
\toggletrue{/longbox/@part-needtop}%
|
||||
\togglefalse{/longbox/@part-needbottom}%
|
||||
\lb@render@vbox{#1}%
|
||||
\lb@eject
|
||||
\endgroup
|
||||
}
|
||||
\newcommand*\lb@middle@[1]{%
|
||||
\begingroup
|
||||
\togglefalse{/longbox/@part-needtop}%
|
||||
\togglefalse{/longbox/@part-needbottom}%
|
||||
\lb@render@vbox{#1}%
|
||||
\lb@eject
|
||||
\endgroup
|
||||
}
|
||||
\newcommand*\lb@last@[1]{%
|
||||
\begingroup
|
||||
\togglefalse{/longbox/@part-needtop}%
|
||||
\toggletrue{/longbox/@part-needbottom}%
|
||||
\lb@render@vbox{#1}%
|
||||
\endgroup
|
||||
}
|
||||
|
||||
% --------------------------------------------------------
|
||||
%
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newcommand*\lb@env@start{%
|
||||
\ifcase\lb@textalign\relax
|
||||
%default
|
||||
\or\raggedright
|
||||
\or\centering
|
||||
\or\raggedleft
|
||||
\else\relax% justify=default
|
||||
\fi
|
||||
\lb@insertbefore
|
||||
}
|
||||
|
||||
\newcount\lb@usevbox
|
||||
\newlength\lb@width
|
||||
\newlength\lb@height
|
||||
\newlength\lb@skiptop
|
||||
\newlength\lb@skipright
|
||||
\newlength\lb@skipbottom
|
||||
\newlength\lb@skipleft
|
||||
\newlength\lb@skipbreaktop
|
||||
\newlength\lb@skipbreakbottom
|
||||
\newlength\lb@outerwidth
|
||||
\newlength\lb@extrasplit
|
||||
\newcount\lb@textalign
|
||||
\newcount\lb@baseline
|
||||
\newtoggle{lb@baselineskip}%
|
||||
\newtoggle{lb@breakable}%
|
||||
\newtoggle{lb@debug}%
|
||||
\newtoggle{lb@verbose}%
|
||||
\def\lb@breakat{}%
|
||||
\def\lb@halign{}%
|
||||
\def\lb@eject{}%
|
||||
\def\lb@insertafter{}
|
||||
\def\lb@insertbefore{}
|
||||
|
||||
\newcommand*\lb@peekoptions[1]{%
|
||||
% process options inside a group and just set necessary parameters
|
||||
% this way, nested boxes don't influence each other's parameters
|
||||
\begingroup
|
||||
\options{#1}%
|
||||
\option{/longbox/adjust-options}%
|
||||
\protected@edef\lb@temp{\endgroup
|
||||
\lb@width=\the\dimexpr\option{/longbox/width}\relax
|
||||
\lb@height=\the\dimexpr\option{/longbox/height}\relax
|
||||
\lb@textalign=\the\numexpr\option{/longbox/text-align/@ord}\relax
|
||||
\lb@baseline=\the\numexpr\option{/longbox/baseline/@ord}\relax
|
||||
\lb@skiptop=\the\dimexpr\option{/longbox/skip-top}\relax
|
||||
\lb@skipright=\the\dimexpr\option{/longbox/skip-right}\relax
|
||||
\lb@skipbottom=\the\dimexpr\option{/longbox/skip-bottom}\relax
|
||||
\lb@skipleft=\the\dimexpr\option{/longbox/skip-left}\relax
|
||||
\lb@skipbreaktop=\the\dimexpr\option{/longbox/skip-break-top}\relax
|
||||
\lb@skipbreakbottom=\the\dimexpr\option{/longbox/skip-break-bottom}\relax
|
||||
\lb@usevbox=\iftoggle{/longbox/use-vbox}{1}{0}\relax
|
||||
\lb@outerwidth=\the\dimexpr\option{/longbox/outer-width}\relax
|
||||
\lb@extrasplit=\the\dimexpr\option{/longbox/split-minimum}\relax
|
||||
\def\noexpand\lb@insertafter{\option{/longbox/insert-after}}%
|
||||
\def\noexpand\lb@insertbefore{\option{/longbox/insert-before}}%
|
||||
\def\noexpand\lb@breakat{\option{/longbox/breakat}}%
|
||||
\def\noexpand\lb@halign{\option{/longbox/height-align}}%
|
||||
\def\noexpand\lb@eject{\option{/longbox/eject}}%
|
||||
\noexpand\csname toggle\iftoggle{/longbox/baseline-skip}{true}{false}\endcsname{lb@baselineskip}%
|
||||
\noexpand\csname toggle\iftoggle{/longbox/breakable}{true}{false}\endcsname{lb@breakable}%
|
||||
\noexpand\csname toggle\iftoggle{/longbox/debug}{true}{false}\endcsname{lb@debug}%
|
||||
\noexpand\csname toggle\iftoggle{/longbox/verbose}{true}{false}\endcsname{lb@verbose}%
|
||||
}%
|
||||
\lb@temp
|
||||
}
|
||||
|
||||
\newenvironment{longbox@env}[2]{%
|
||||
% save options
|
||||
\lb@peekoptions{#1,#2}%
|
||||
%
|
||||
\ifnum\lb@usevbox=0\relax
|
||||
\lb@debug{start breakbox}%
|
||||
\let\bb@render\lb@render@breakbox
|
||||
\bb@savekeys{longbox}{options={#1,#2,outer-width=\the\lb@outerwidth}}%
|
||||
\iftoggle{lb@baselineskip}{\typeout{**insert bskip}}{\typeout{**suppress bskip}\vskip 1pt}%
|
||||
\begin{breakbox}%
|
||||
\ifdim\lb@skiptop=\z@\relax\else\vspace{\lb@skiptop}\fi%
|
||||
\dimen@=\dimexpr\linewidth-\lb@skipleft-\lb@width\relax
|
||||
\begin{bb@margins}{\lb@skipleft}{\dimen@}%
|
||||
\else
|
||||
\lb@debug{start vbox}%
|
||||
\def\lb@restoreoptions{\options{#1,#2}\option{/longbox/adjust-options}}%
|
||||
\lb@savefootnotes
|
||||
\dimen@=\dimexpr\linewidth-\lb@skipleft-\lb@width\relax
|
||||
\lb@debug{ width=\the\lb@width, linewidth=\the\linewidth, skipleft=\the\lb@skipleft, right=\the\lb@skipright, total right=\the\dimen@}%
|
||||
\iftoggle{lb@baselineskip}{\lb@skiptobaseline}{\lb@prevdepth=-\@m pt}%
|
||||
\lvbox{\lb@mainbox}{0pt}{\lb@width}{0pt}%{\lb@skipleft}{\lb@width}{\lb@skipright}%
|
||||
\prevdepth=\lb@prevdepth
|
||||
\fi
|
||||
\ifcase\lb@textalign\relax
|
||||
%default
|
||||
\or\raggedright
|
||||
\or\centering
|
||||
\or\raggedleft
|
||||
\else\relax% justify=default
|
||||
\fi
|
||||
\lb@insertbefore
|
||||
\begingroup
|
||||
}{%
|
||||
\par\unskip
|
||||
\endgroup
|
||||
\lb@insertafter
|
||||
%\ifdim\lb@skipbottom=\z@\relax\else\vskip\lb@skipbottom\fi%
|
||||
\ifnum\lb@usevbox=0\relax
|
||||
\end{bb@margins}%
|
||||
\ifdim\lb@skipbottom=\z@\relax\else\hrule width \z@ height \lb@skipbottom\fi%\vspace{\lb@skipbottom}\fi%
|
||||
\iftoggle{lb@baselineskip}{}{\vskip 1sp}%
|
||||
\end{breakbox}%
|
||||
\lb@debug{end breakbox}%
|
||||
\else
|
||||
\ontoggle{lb@baselineskip}{\lb@skiptobaseline}%
|
||||
\endlvbox%
|
||||
\lb@debug{initial lvbox: \the\dp\lb@mainbox, \the\ht\lb@mainbox, \the\wd\lb@mainbox}%
|
||||
\lb@processbox
|
||||
%\setbox\lb@mainbox=\hbox{\lower \lb@skipbottom\vbox{\offinterlineskip\unvbox\lb@mainbox}}%
|
||||
\lb@restorefootnotes
|
||||
\lb@debug{end vbox}%
|
||||
\fi
|
||||
}
|
||||
|
||||
\newcommand\longbox@cmd[3]{%
|
||||
\begingroup
|
||||
%\options{/options/collectunknown,/longbox/scoped,#2}% set scoped options first
|
||||
%\option{/longbox/scoped/@adjust-options}%
|
||||
\lb@peekoptions{#1,#2}%
|
||||
\leavevmode
|
||||
%\setbox\lb@mainbox=\hbox{%
|
||||
% \begingroup
|
||||
% #3%
|
||||
% \endgroup
|
||||
%}%
|
||||
\setbox\lb@mainbox=\hbox{%
|
||||
\begingroup
|
||||
\ifcase\lb@textalign\relax
|
||||
%default=left
|
||||
\or%left
|
||||
\or\hss%center
|
||||
\or\hss%right
|
||||
\else%justify
|
||||
\fi
|
||||
\lb@insertbefore
|
||||
#3%
|
||||
\lb@insertafter
|
||||
\ifnum\lb@textalign<3\relax\hss\fi% default,left,center
|
||||
\endgroup
|
||||
}%
|
||||
\options{#1,#2}%
|
||||
\ifdim\option{/longbox/width}=-1sp\relax
|
||||
\options{/longbox/width=\wd\lb@mainbox}%set to natural width
|
||||
\fi
|
||||
\option{/longbox/adjust-options}%
|
||||
% make it a vbox
|
||||
\setbox\lb@mainbox=\vbox{\offinterlineskip%
|
||||
\hbox to \option{/longbox/width}{%
|
||||
\unhbox\lb@mainbox
|
||||
}%
|
||||
}%
|
||||
\def\lb@restoreoptions{}%
|
||||
\letoption{/longbox/height-align}\lb@halign
|
||||
\lb@height=\option{/longbox/height}\relax
|
||||
\lb@baseline=\option{/longbox/baseline/@ord}\relax
|
||||
\lb@processbox
|
||||
\endgroup
|
||||
}
|
||||
|
||||
\newcommand\lb@processbox{%
|
||||
\ifdim\lb@height<0pt\relax
|
||||
\lb@setbaseline{\lb@mainbox}%
|
||||
\else
|
||||
\lb@restrictheight
|
||||
\fi
|
||||
\lb@typesetbox
|
||||
}
|
||||
|
||||
\newcommand\lb@typesetbox{%
|
||||
\ifinlvbox
|
||||
\iftoggle{lb@breakable}{%
|
||||
%\lb@debug{disable breakable due to nesting of long-boxes}%
|
||||
\togglefalse{lb@breakable}%
|
||||
}{}%
|
||||
\fi
|
||||
\ifhmode\lb@single@{\lb@mainbox}\else\lb@typeset\fi
|
||||
}
|
||||
|
||||
% --------------------------------------------------------
|
||||
%
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newcommand\lb@restrictheight{%
|
||||
\lb@typeout{restrict height to \the\lb@height}%
|
||||
\lb@splitheight=\lb@height%
|
||||
%lb@debug{before height split: \the\dp\lb@mainbox, \the\ht\lb@mainbox, \the\wd\lb@mainbox}%
|
||||
\lb@splitbox
|
||||
\ifdim\ht\lb@headbox=0pt\relax
|
||||
%split failed.. do nothing
|
||||
\lb@debug{could not restrict height}%
|
||||
\else
|
||||
% store splitted off content in the mainbox (and discard the rest)
|
||||
\setbox\lb@mainbox\vbox{\unvbox\lb@headbox}%
|
||||
\lb@debug{restricted height to \the\ht\lb@mainbox}%
|
||||
\fi
|
||||
% set baseline
|
||||
\lb@setbaseline{\lb@mainbox}%
|
||||
% height align
|
||||
%\letoption{/longbox/height-align}\lb@halign
|
||||
\eifstrequal{\lb@halign}{bottom}%
|
||||
{\setbox\lb@mainbox=\vbox{\hbox{\vbox to \lb@splitheight{\vss\unvbox\lb@mainbox}}}}%
|
||||
{\eifstrequal{\lb@halign}{middle}%
|
||||
{\dimen@=\dimexpr\lb@splitheight-\ht\lb@mainbox-\dp\lb@mainbox\relax
|
||||
\setbox\lb@mainbox=\vbox{\hbox{%
|
||||
\lower \dimexpr0.5\dimen@ + \dp\lb@mainbox\relax%
|
||||
\vbox to \lb@splitheight{\vss\unvbox\lb@mainbox\vss}}}}%
|
||||
{% default is top
|
||||
\dimen@=\dimexpr\lb@splitheight-\ht\lb@mainbox-\dp\lb@mainbox\relax
|
||||
\setbox\lb@mainbox=\vbox{\vtop to \lb@splitheight{\box\lb@mainbox\vss}}%
|
||||
}%
|
||||
}%
|
||||
}
|
||||
|
||||
% --------------------------------------------------------
|
||||
%
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newlength\lb@neededvspace
|
||||
\newcommand\lb@typeset[1][0pt]{%
|
||||
\iftoggle{lb@breakable}{%
|
||||
\lb@setfreevspace
|
||||
\setlength\lb@neededvspace{\dimexpr\ht\lb@mainbox+\dp\lb@mainbox+\lb@skiptop+\lb@skipbottom\relax}%
|
||||
\lb@debug{needed: \the\lb@neededvspace, available: \the\lb@freevspace}%
|
||||
\ifdim\lb@neededvspace<\lb@freevspace\relax
|
||||
\lb@single@{\lb@mainbox}%
|
||||
\else
|
||||
\lb@typeout{longbox needs splitting}%
|
||||
\setlength\lb@splitheight{\dimexpr\lb@freevspace-\lb@skiptop-\lb@skipbreakbottom\relax}%
|
||||
\lb@splitbox
|
||||
\ifdim\ht\lb@headbox=0pt\relax
|
||||
% failed to split
|
||||
\ifdim\dimexpr\lb@freevspace + #1\relax<\textheight\relax % test if we were at a fresh page.. (and prevent infinite recursion)
|
||||
\lb@debug{failed to split the box, inserting a page break}%
|
||||
\hrule \@height\z@ \@width\hsize
|
||||
\lb@eject%
|
||||
\lb@typeset[\textheight]% try again, but pass \textheight to guard against infinite recursion
|
||||
\else
|
||||
% on a fresh page we should not fail anymore.. just output as is..
|
||||
% lb@warncannotsplit
|
||||
\lb@single@{\lb@mainbox}%
|
||||
\fi
|
||||
\else
|
||||
% first part success
|
||||
\lb@typeout{first part splitted}%
|
||||
\lb@first@{\lb@headbox}%
|
||||
\expandafter\expandafter\expandafter\lb@typesetrest
|
||||
\fi
|
||||
\fi
|
||||
}{%\else
|
||||
\lb@debug{unbreakable box}%
|
||||
\lb@single@{\lb@mainbox}% always directly output an unbreakable box
|
||||
}%
|
||||
}
|
||||
|
||||
\newcommand\lb@typesetrest{%
|
||||
\lb@setfreevspace%
|
||||
\setlength\lb@neededvspace{\dimexpr\ht\lb@mainbox+\dp\lb@mainbox+\lb@skipbottom+\lb@skipbreaktop\relax}%
|
||||
\ifdim\lb@neededvspace<\lb@freevspace\relax
|
||||
\lb@typeout{output last part of box}%
|
||||
\lb@last@{\lb@mainbox}%
|
||||
\else
|
||||
\lb@debug{split box further}%
|
||||
\setlength\lb@splitheight{\dimexpr\lb@freevspace-\lb@skipbreaktop-\lb@skipbreakbottom\relax}%
|
||||
\lb@splitbox
|
||||
\ifdim\ht\lb@headbox=0pt\relax
|
||||
% failed to split
|
||||
\lb@typeout{failed to split box!}%
|
||||
\lb@last@{\lb@mainbox}%
|
||||
\else
|
||||
% middle part success
|
||||
\lb@typeout{output middle part of box}%
|
||||
\lb@middle@{\lb@headbox}%
|
||||
\expandafter\expandafter\expandafter\lb@typesetrest% continue the iteration...
|
||||
\fi
|
||||
\fi
|
||||
}
|
||||
|
||||
% --------------------------------------------------------
|
||||
% Split a long vbox over multiple pages.
|
||||
% This code is based on similar code in the mdframed package
|
||||
% --------------------------------------------------------
|
||||
|
||||
\newlength\lb@splitheight
|
||||
\newlength\lb@insurance % tiny extra space to ensure our box will really fit
|
||||
\setlength\lb@insurance{1pt}
|
||||
|
||||
% expects split target height in lb@splitheight, and splits off the start of lb@mainbox to lb@headbox
|
||||
\newcommand\lb@splitbox{%
|
||||
\ifdim\dimexpr\ht\lb@mainbox + \dp\lb@mainbox\relax>\lb@splitheight\relax
|
||||
% the main box is larger than our target split height..
|
||||
\ifdim\lb@extrasplit>\lb@splitheight\relax
|
||||
% not enough space to bother
|
||||
\lb@typeout{not enough space on page for a split}%
|
||||
\setbox\lb@headbox=\vbox{}% empty head
|
||||
\else
|
||||
% try a split; lower the split height a bit so we are sure to fit
|
||||
\advance\lb@splitheight -\lb@insurance\relax
|
||||
\lb@debug{split: \the\lb@splitheight, from \the\dimexpr\ht\lb@mainbox + \dp\lb@mainbox\relax}%
|
||||
\setbox\lb@savebox=\vbox{\unvcopy\lb@mainbox}% save original
|
||||
\lb@trysplit{\lb@splitheight}%
|
||||
\ifdim\dimexpr\ht\lb@headbox + \dp\lb@headbox>\lb@splitheight\relax
|
||||
% too big, bad split. Try other splits.. iterate N times with 1 or 5pt less before giving up
|
||||
\dimen@=\lb@splitheight\relax
|
||||
\@tempcnta=\z@\relax
|
||||
\loop
|
||||
\ifdim\dimexpr\ht\lb@headbox+\dp\lb@headbox\relax>\lb@splitheight\relax
|
||||
\ifnum\@tempcnta<50%
|
||||
\advance\dimen@ by -\p@\relax% try a slightly smaller height..
|
||||
\else
|
||||
\advance\dimen@ by -5\p@\relax% try larger increase after 50pt..
|
||||
\fi
|
||||
\advance\@tempcnta by \@ne\relax
|
||||
\lb@ignorevbadness
|
||||
\setbox\lb@mainbox=\vbox{\unvcopy\lb@savebox}% restore
|
||||
\lb@trysplit{\dimen@}%
|
||||
\ifdim\lb@extrasplit<\dimen@\relax\else\lb@splitstop\fi % don't try to split too small
|
||||
\ifnum\@tempcnta<100\relax\else\lb@splitstop\fi % and not more than N attempts
|
||||
\repeat%
|
||||
\ifnum\@tempcnta<100\relax
|
||||
\dimen@=\dimexpr\lb@splitheight - \ht\lb@headbox - \dp\lb@headbox\relax
|
||||
\ifdim\dimen@>\option{/longbox/split-badness}\relax
|
||||
\lb@warnbadsplit{\dimen@}%
|
||||
\fi
|
||||
\fi
|
||||
\fi
|
||||
\fi
|
||||
\else
|
||||
% mainbox fits in our target lb@splitheight
|
||||
\setbox\lb@headbox=\vbox{\unvbox\lb@mainbox}%
|
||||
\setbox\lb@mainbox=\vbox{}%
|
||||
\fi
|
||||
}
|
||||
|
||||
\newcommand\lb@splitstop{%
|
||||
\lb@typeout{cannot find a good split}%
|
||||
\let\iterate\relax
|
||||
\lb@warncannotsplit
|
||||
\setbox\lb@mainbox=\vbox{\unvcopy\lb@savebox}% restore
|
||||
\setbox\lb@headbox=\vbox{}% empty head
|
||||
\@tempcnta=\@M\relax
|
||||
}
|
||||
|
||||
\newcommand\lb@trysplit[1]{% try to split at given height
|
||||
\lb@typeout{try to split at: \the\dimexpr #1\relax}%
|
||||
\lb@ignorevbadness
|
||||
\setbox\lb@headbox=\vsplit\lb@mainbox to #1\relax%
|
||||
\setbox\lb@headbox=\vbox{\unvbox\lb@headbox}%
|
||||
\setbox\lb@mainbox=\vbox{\unvbox\lb@mainbox}%
|
||||
}
|
||||
|
||||
% --------------------------------------------------------
|
||||
% The longbox environment uses options to set its options
|
||||
% --------------------------------------------------------
|
||||
|
||||
|
||||
% keys and styles that can be set once globally
|
||||
\options{%
|
||||
/longbox/.new family,
|
||||
}%
|
||||
|
||||
\options{/longbox,%
|
||||
% computed
|
||||
@part-needtop/.new toggle,
|
||||
@part-needbottom/.new toggle,
|
||||
@part-height/.new length,
|
||||
@part-width/.new length,
|
||||
@part-depth/.new length,
|
||||
@content-box-height/.new length,
|
||||
@content-box-width/.new length,
|
||||
@content-box-depth/.new length,
|
||||
@breakat-previous/.new length,
|
||||
@lower/.new length,
|
||||
%
|
||||
debug/.new toggle,
|
||||
verbose/.new toggle,
|
||||
render/.new value =\lb@render@fbox,
|
||||
adjust-options/.new value = {\longbox@adjustoptions},
|
||||
eject/.new value = {\protect\vfill\protect\eject},
|
||||
use-vbox/.new toggle = true,
|
||||
split-minimum/.new length = {1.5\baselineskip},
|
||||
split-badness/.new length = \baselineskip,
|
||||
%
|
||||
height-align/.new choice= {top,middle,bottom},
|
||||
baseline/.new choice = {bottom,middle,top},
|
||||
text-align/.new choice = {default,left,center,right,justify},
|
||||
vertical-align/.new choice = {baseline,bottom,middle,top,text-bottom,text-top,super,sub},
|
||||
raise/.new length = {0pt},
|
||||
baseline-skip/.new toggle =true,
|
||||
%
|
||||
height/.new length = -1sp,
|
||||
width/.new length = -1sp,
|
||||
outer-height/.new length= -1sp,
|
||||
outer-width/.new length = -1sp,
|
||||
insert-before/.new value= {},
|
||||
insert-after/.new value = {},
|
||||
breakat/.new value = {},
|
||||
breakable/.new toggle = false,
|
||||
skip/.new style = {skip-top=#1,skip-right=#1,skip-bottom=#1,skip-left=#1},
|
||||
skip-top/.new length,
|
||||
skip-right/.new length,
|
||||
skip-bottom/.new length,
|
||||
skip-left/.new length,
|
||||
skip-break-bottom/.new length,
|
||||
skip-break-top/.new length,
|
||||
}
|
||||
|
||||
\newcommand\longbox@adjustoptions{%
|
||||
%\typeout{ standard longbox adjustoptions}%
|
||||
\lb@debug{ current width=\the\dimexpr\option{/longbox/width}, outer=\the\dimexpr\option{/longbox/outer-width}, linewidth=\the\linewidth}%
|
||||
\ontoggle{/longbox/debug}{\option@invoke{/longbox/verbose}{true}}%
|
||||
% adjust height
|
||||
\ifdim\option{/longbox/height}=-1sp\relax
|
||||
\ifdim\option{/longbox/outer-height}=-1sp\else
|
||||
\option@invoke{/longbox/height}%
|
||||
{\option{/longbox/outer-height}-\option{/longbox/skip-top}-\option{/longbox/skip-bottom}}%
|
||||
\fi
|
||||
\fi
|
||||
% set width
|
||||
\ifdim\option{/longbox/width}=-1sp\relax
|
||||
\ifdim\option{/longbox/outer-width}=-1sp\relax
|
||||
\option@invoke{/longbox/outer-width}{\linewidth}%
|
||||
\fi
|
||||
\dimen@=\dimexpr\option{/longbox/outer-width}-\option{/longbox/skip-left}-\option{/longbox/skip-right}\relax
|
||||
\ifdim\dimen@<\z@\relax\dimen@=\z@\fi
|
||||
\option@invoke{/longbox/width}{\dimen@}%
|
||||
\fi
|
||||
% use a breakbox whenever we are in external vertical mode and not width or height restricted.
|
||||
\iftoggle{/longbox/use-vbox}{}{%
|
||||
\ifinner\toggletrue{/longbox/use-vbox}\else
|
||||
\ifhmode\toggletrue{/longbox/use-vbox}\else
|
||||
\ifdim\option{/longbox/height}>-1sp\toggletrue{/longbox/use-vbox}\else
|
||||
\iftoggle{/longbox/breakable}{}{\toggletrue{/longbox/use-vbox}}%
|
||||
\ifoptionblank{/longbox/breakat}{}{\toggletrue{/longbox/use-vbox}}%
|
||||
\fi\fi\fi
|
||||
}%
|
||||
}
|
||||
|
||||
\newenvironment{longbox}[1][]{%
|
||||
%\bb@savekeys{bfbox}{fboxrule=\the\fboxrule,fboxsep=\the\fboxsep,bgcolor={\bb@bgcolor},rulecolor={\bb@rulecolor},stickout={\bb@stickout}}%
|
||||
\begin{longbox@env}{/longbox}{#1}%
|
||||
}{\end{longbox@env}}
|
||||
|
||||
\newcommand\lbox[1][]{%
|
||||
%\bb@savekeys{bfbox}{fboxrule=\the\fboxrule,fboxsep=\the\fboxsep,bgcolor={\bb@bgcolor},rulecolor={\bb@rulecolor},stickout={\bb@stickout}}%
|
||||
\longbox@cmd{/longbox}{#1}%
|
||||
}
|
||||
|
||||
\newcommand*\lb@render@fbox{%
|
||||
%\typeout{render defaultbox: bgcolor=\bb@bgcolor, needtop=\iftoggle{/longbox/@part-needtop}{true}{false}}%
|
||||
\@ovdx=\dimexpr\option{/longbox/@part-width} - 2\fboxrule\relax%
|
||||
\@ovdy=\dimexpr\option{/longbox/@part-height}\relax%
|
||||
\iftoggle{/longbox/@part-needbottom}%
|
||||
{\@tempdima=0pt\relax\advance\@ovdy by -\fboxrule}%
|
||||
{\@tempdima=\dimexpr\fboxrule + \bb@stickout\relax
|
||||
\advance\bb@height by \@tempdima
|
||||
\advance\@ovdy by \@tempdima}%
|
||||
\iftoggle{/longbox/@part-needtop}%
|
||||
{\@tempdimb=0pt\relax\advance\@ovdy by -\fboxrule}%
|
||||
{\@tempdimb=\dimexpr\bb@stickout\relax
|
||||
\advance\bb@height by \@tempdimb
|
||||
\advance\@ovdy by \@tempdimb}%
|
||||
%
|
||||
\hbox{\lower \@tempdima\vbox{%
|
||||
\vskip -\@tempdimb
|
||||
\ontoggle{/longbox/@part-needtop}{\lb@debug{toprule wd=\expandafter\the\option{/longbox/width}}\hrule width \option{/longbox/@part-width} height \fboxrule}%
|
||||
\hbox{%
|
||||
\vrule width \fboxrule height \@ovdy%
|
||||
\ifx\bb@bgcolor\@empty
|
||||
\vrule width \@ovdx height \z@\relax
|
||||
\else
|
||||
{\color{\bb@bgcolor}\vrule width \@ovdx height \@ovdy}%
|
||||
\fi
|
||||
\vrule width \fboxrule height \@ovdy%
|
||||
}%
|
||||
\ontoggle{/longbox/@part-needbottom}{\hrule width \option{/longbox/@part-width} height \fboxrule}%
|
||||
}}%
|
||||
}
|
||||
1344
out/longfbox.sty
1344
out/longfbox.sty
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
377
out/madoko.css
377
out/madoko.css
|
|
@ -1,377 +0,0 @@
|
|||
/* ---------------------------------------------------
|
||||
Various settings to display madoko elements correctly.
|
||||
For example, lines in tables or a table of contents.
|
||||
|
||||
All rules use specific madoko classes and never just
|
||||
a generic element. This means one can safely include
|
||||
this CSS into any web page without affecting non-madoko
|
||||
content.
|
||||
----------------------------------------------------*/
|
||||
|
||||
/* The table of contents */
|
||||
.madoko .toc>.tocblock .tocblock .tocblock {
|
||||
margin-left: 2.25em;
|
||||
}
|
||||
|
||||
.madoko .toc>.tocblock .tocblock {
|
||||
margin-left: 1.5em;
|
||||
}
|
||||
|
||||
.madoko .toc-contents>.tocblock>.tocitem {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.madoko .toc {
|
||||
margin-top: 1em;
|
||||
}
|
||||
|
||||
/* Paragraphs */
|
||||
.madoko p.para-continue {
|
||||
margin-bottom: 0pt;
|
||||
}
|
||||
|
||||
.madoko .para-block+p {
|
||||
margin-top: 0pt;
|
||||
}
|
||||
|
||||
.madoko ul.para-block, .madoko ol.para-block {
|
||||
margin-top: 0pt;
|
||||
margin-bottom: 0pt;
|
||||
}
|
||||
|
||||
.madoko ul.para-end, .madoko ol.para-end {
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.madoko dl {
|
||||
margin-left: 0em;
|
||||
}
|
||||
|
||||
.madoko blockquote {
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
/* Local page links do not get an underline unless hovering */
|
||||
.madoko a.localref {
|
||||
text-decoration: none;
|
||||
}
|
||||
.madoko a.localref:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/* Footnotes */
|
||||
.madoko .footnotes {
|
||||
font-size: smaller;
|
||||
margin-top: 2em;
|
||||
}
|
||||
|
||||
.madoko .footnotes hr {
|
||||
width: 50%;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.madoko .footnote {
|
||||
margin-left: 1em;
|
||||
}
|
||||
.madoko .footnote-before {
|
||||
margin-left: -1em;
|
||||
width: 1em;
|
||||
display: inline-block;
|
||||
}
|
||||
|
||||
/* Alignment */
|
||||
.madoko .align-center, .madoko .align-center>p {
|
||||
text-align: center !important;
|
||||
}
|
||||
|
||||
.madoko .align-center pre {
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.madoko .align-center>* {
|
||||
margin-left: auto !important;
|
||||
margin-right: auto !important;
|
||||
}
|
||||
|
||||
.madoko .align-left, .madoko .align-left>p {
|
||||
text-align: left !important;
|
||||
}
|
||||
|
||||
.madoko .align-left>* {
|
||||
margin-left: 0pt !important;
|
||||
margin-right: auto !important;
|
||||
}
|
||||
|
||||
.madoko .align-right, .madoko .align-right>p {
|
||||
text-align: right !important;
|
||||
}
|
||||
|
||||
.madoko .align-right>* {
|
||||
margin-left: auto !important;
|
||||
margin-right: 0pt !important;
|
||||
}
|
||||
|
||||
.madoko .align-center>table,
|
||||
.madoko .align-left>table,
|
||||
.madoko .align-right>table {
|
||||
text-align: left !important;
|
||||
}
|
||||
|
||||
|
||||
/* Equations, Figure's etc. */
|
||||
.madoko .equation-before {
|
||||
float: right;
|
||||
}
|
||||
|
||||
/* Bibliography */
|
||||
.madoko .bibitem {
|
||||
font-size: smaller;
|
||||
}
|
||||
|
||||
.madoko .bibsearch {
|
||||
font-size: x-small;
|
||||
text-decoration:none;
|
||||
color: black;
|
||||
font-family: "Segoe UI Symbol", Symbola, serif;
|
||||
}
|
||||
|
||||
/* General */
|
||||
.madoko .block, .madoko .figure, .madoko .bibitem, .madoko .equation, .madoko div.math {
|
||||
margin-top: 1ex;
|
||||
margin-bottom: 1ex;
|
||||
}
|
||||
|
||||
.madoko .figure {
|
||||
padding: 0.5em;
|
||||
margin-left: 0pt;
|
||||
margin-right: 0pt;
|
||||
}
|
||||
|
||||
.madoko .hidden {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.madoko .invisible {
|
||||
visibility: hidden;
|
||||
}
|
||||
|
||||
.madoko.preview .invisible {
|
||||
visibility: visible;
|
||||
opacity: 0.5;
|
||||
}
|
||||
|
||||
.madoko code.code, .madoko span.code {
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
|
||||
.madoko hr, hr.madoko {
|
||||
border: none;
|
||||
border-bottom: black solid 1px;
|
||||
margin-bottom: 0.5ex;
|
||||
}
|
||||
|
||||
.madoko .framed>*:first-child {
|
||||
margin-top: 0pt;
|
||||
}
|
||||
.madoko .framed>*:last-child {
|
||||
margin-bottom: 0pt;
|
||||
}
|
||||
|
||||
/* Lists */
|
||||
|
||||
.madoko ul.list-style-type-dash {
|
||||
list-style-type: none !important;
|
||||
}
|
||||
|
||||
.madoko ul.list-style-type-dash > li:before {
|
||||
content: "\2013";
|
||||
position: absolute;
|
||||
margin-left: -1em;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
.madoko table.madoko {
|
||||
border-collapse: collapse;
|
||||
}
|
||||
.madoko td, .madoko th {
|
||||
padding: 0ex 0.5ex;
|
||||
margin: 0pt;
|
||||
vertical-align: top;
|
||||
}
|
||||
|
||||
.madoko .cell-border-left {
|
||||
border-left: 1px solid black;
|
||||
}
|
||||
.madoko .cell-border-right {
|
||||
border-right: 1px solid black;
|
||||
}
|
||||
|
||||
|
||||
.madoko thead>tr:first-child>.cell-line,
|
||||
.madoko tbody:first-child>tr:first-child>.cell-line {
|
||||
border-top: 1px solid black;
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
.madoko .cell-line, .madoko .cell-double-line {
|
||||
border-bottom: 1px solid black;
|
||||
border-top: none;
|
||||
}
|
||||
|
||||
.madoko .cell-double-line {
|
||||
border-top: 1px solid black;
|
||||
padding-top: 1.5px !important;
|
||||
}
|
||||
|
||||
|
||||
/* Math Pre */
|
||||
.madoko .input-mathpre .MathJax_Display {
|
||||
text-align: left !important;
|
||||
}
|
||||
|
||||
.madoko div.input-mathpre {
|
||||
text-align: left;
|
||||
margin-top: 1.5ex;
|
||||
margin-bottom: 1ex;
|
||||
}
|
||||
|
||||
.madoko .math-rendering {
|
||||
text-align: left;
|
||||
white-space: pre;
|
||||
color: gray;
|
||||
}
|
||||
|
||||
.madoko .mathdisplay {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
|
||||
/*---------------------------------------------------------------------------
|
||||
Default style for syntax highlighting
|
||||
---------------------------------------------------------------------------*/
|
||||
|
||||
.madoko .pretty table {
|
||||
border-collapse: collapse;
|
||||
}
|
||||
.madoko .pretty td {
|
||||
padding: 0em;
|
||||
}
|
||||
.madoko .pretty td.empty {
|
||||
min-width: 1.5ex;
|
||||
}
|
||||
.madoko .pretty td.expander {
|
||||
width: 100em;
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------
|
||||
Styling for full documents
|
||||
----------------------------------------------------*/
|
||||
body.madoko, .madoko .serif {
|
||||
font-family: Cambria,"Times New Roman","Liberation Serif","Times",serif;
|
||||
}
|
||||
.madoko .sans-serif {
|
||||
font-family: "Calibri", "Optima", sans-serif;
|
||||
}
|
||||
.madoko .symbol {
|
||||
font-family: "Segoe UI Symbol", Symbola, serif;
|
||||
}
|
||||
|
||||
|
||||
body.madoko {
|
||||
-webkit-text-size-adjust: 100%; /* so math displays well on mobile devices */
|
||||
text-rendering: optimizeLegibility;
|
||||
}
|
||||
|
||||
body.madoko {
|
||||
max-width: 88ex; /* about 88 characters */
|
||||
margin: 1em auto;
|
||||
padding: 0em 2em;
|
||||
}
|
||||
|
||||
body.preview.madoko {
|
||||
padding: 0em 1em;
|
||||
}
|
||||
|
||||
.madoko p {
|
||||
text-align: justify;
|
||||
}
|
||||
|
||||
/* style headings nicer, especially h5 and h6 */
|
||||
.madoko h1, .madoko h2, .madoko h3, .madoko h4 {
|
||||
margin-top: 1.22em;
|
||||
margin-bottom: 1ex;
|
||||
}
|
||||
.madoko h1+p, .madoko h2+p, .madoko h3+p, .madoko h4+p, .madoko h5+p {
|
||||
margin-top: 1ex;
|
||||
}
|
||||
.madoko h5, .madoko h6 {
|
||||
margin-top: 1ex;
|
||||
font-size: 1em;
|
||||
}
|
||||
.madoko h5 {
|
||||
margin-bottom: 0.5ex;
|
||||
}
|
||||
.madoko h5 + p {
|
||||
margin-top: 0.5ex;
|
||||
}
|
||||
.madoko h6 {
|
||||
margin-bottom: 0pt;
|
||||
}
|
||||
.madoko h6 + p {
|
||||
margin-top: 0pt;
|
||||
}
|
||||
|
||||
|
||||
/* Fix monospace display (see http://code.stephenmorley.org/html-and-css/fixing-browsers-broken-monospace-font-handling/) */
|
||||
.madoko pre, .madoko code, .madoko kbd, .madoko samp, .madoko tt,
|
||||
.madoko .monospace, .madoko .token-indent, .madoko .reveal pre, .madoko .reveal code, .madoko .email {
|
||||
font-family: Consolas,"Andale Mono WT","Andale Mono",Lucida Console,Monaco,monospace,monospace;
|
||||
font-size: 0.85em;
|
||||
}
|
||||
.madoko pre code, .madoko .token-indent {
|
||||
font-size: 0.95em;
|
||||
}
|
||||
|
||||
.madoko pre code {
|
||||
font-family: inherit !important;
|
||||
}
|
||||
|
||||
/* Code prettify */
|
||||
.madoko ol.linenums li {
|
||||
background-color: white;
|
||||
list-style-type: decimal;
|
||||
}
|
||||
|
||||
/* Merging */
|
||||
.madoko .remote {
|
||||
background-color: #F0FFF0;
|
||||
}
|
||||
.madoko .remote + * {
|
||||
margin-top: 0pt;
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------
|
||||
Print settings
|
||||
----------------------------------------------------*/
|
||||
|
||||
@media print {
|
||||
body.madoko {
|
||||
font-size: 10pt;
|
||||
}
|
||||
@page {
|
||||
margin: 1in 1.5in;
|
||||
}
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------
|
||||
Mobile device settings
|
||||
----------------------------------------------------*/
|
||||
|
||||
@media only screen and (max-device-width:1024px) {
|
||||
body.madoko {
|
||||
padding: 0em 0.5em;
|
||||
}
|
||||
.madoko li {
|
||||
text-align: left;
|
||||
}
|
||||
}
|
||||
1311
out/madoko2.sty
1311
out/madoko2.sty
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
1387
out/options.sty
1387
out/options.sty
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
Загрузка…
Ссылка в новой задаче