|
13 | 13 | - [Autogenerated Documentation](#autodocs)
|
14 | 14 | - [Custom Documentation](#customdocs)
|
15 | 15 | - [Development Status](#status)
|
| 16 | +- [Pubic Release Notes](#releasenotes) |
16 | 17 |
|
17 | 18 |
|
18 | 19 | ## Installation and Development<a name="install"></a>
|
@@ -210,9 +211,53 @@ One of the outstanding features of sphinx is its support for arbitrarily organiz
|
210 | 211 | materials such as tutorials, introductions, and other context-providing content. These items should
|
211 | 212 | be stored in source control under the `docs/source` directory in properly formatted `.rst` files.
|
212 | 213 |
|
213 |
| - |
214 |
| - |
215 | 214 | ## Development Status<a name="status"></a>
|
216 | 215 |
|
217 | 216 | Classes and methods may be marked as *alpha* by including `[ALPHA]` at the start of their docstrings.
|
218 |
| -These methods are intended for development, testing, and experimentation, are not supported, and may change or be removed without notice |
| 217 | +These methods are intended for development, testing, and experimentation, are not supported, and may change or be removed without notice. |
| 218 | + |
| 219 | +## Public Release Notes<a name="releasenotes"></a> |
| 220 | + |
| 221 | +When releasing a version of Citrine Python for use by customers through exchanges like PyPI, |
| 222 | +include release notes in the folloing template format. |
| 223 | + |
| 224 | +### vx.x.x is released! |
| 225 | +Here is a short overview of the main changes in this release. |
| 226 | +This is written in a friendly tone, avoids jargon, and conveys enthusiasm! |
| 227 | +This section should be ~2-3 sentences and highlight the “what” and the “why” of this release. |
| 228 | +Citrine has a personality, and its personality should come through in both this paragraph and the writing through the release notes. |
| 229 | + |
| 230 | +### What’s New |
| 231 | +* DO: Use these bullets to specify new and never before seen features |
| 232 | +* DO: Add a short description of each new feature and its name if it has one |
| 233 | +* DO: Share particularly exciting screenshots or GIFs of new features easily encapsulated in an image format |
| 234 | +* DO: Keep each bullet to 1-3 sentences (3 sentences max, 1-2 ideal), but DO use sub-lists if a new feature requires extra explanation |
| 235 | +* DO: Include links in each bullet to any important public-facing landing pages, docs, blog posts, resources, etc. relevant to the feature being discussed |
| 236 | +* DON’T: Use these bullets to talk about improvements, that’s the next section! |
| 237 | +* DON’T: Use these bullets to talk about bug fixes, that’s later! |
| 238 | +* DON’T: Use these bullets to discuss things still in progress |
| 239 | +* EXAMPLE: Likes have been in development for 6 months and now that they’re here, you can finally let your friends know how much you appreciate their content. Below each post is now a Like button you can click to express your enthusiasm. |
| 240 | + |
| 241 | +### Improvements |
| 242 | +* DO: Use these bullets to specify aspects of the product that have a better UI/UX |
| 243 | +* DO: Use these bullets to specify aspects of the product that are faster or more performant |
| 244 | +* DO: Use these bullets to address improvements requested by users |
| 245 | +* DO: Share particularly exciting screenshots or GIFs of improvements easily encapsulated in an image format |
| 246 | +* DO: Keep each bullet to 1-3 sentences (3 sentences max, 1-2 ideal) |
| 247 | +* DON’T: Use these bullets to talk about bug fixes, that’s the next section! |
| 248 | +* DON’T: Use these bullets to discuss things still in progress |
| 249 | +* EXAMPLE: Uploading content to the platform has never been faster. With this release, something that took 30 seconds before now should now use much less time. |
| 250 | + |
| 251 | +### Fixes |
| 252 | +* DO: Use these bullets to describe specific bug fixes |
| 253 | +* DO: Explain the before and after of the bug fix |
| 254 | +* DO: Keep each bullet to 1-3 sentences (3 sentences max, 1-2 ideal) |
| 255 | +* DON’T: Use these bullets to talk about general improvements that were not actually bugs |
| 256 | +* EXAMPLE: A bug causing a confusing error message when entering an incorrect password has been fixed. |
| 257 | +Now, if you type your password incorrectly you’ll get a helpful message and a link to reset your password. |
| 258 | + |
| 259 | +### Deprecated |
| 260 | +* DO: Use these bullets to list features that are now deprecated |
| 261 | +* DO: Explain how the deprecated feature will be replaced, if it will, or other key workarounds. |
| 262 | +* DO: Give a very brief explanation for the deprecation. |
| 263 | +* EXAMPLE: As of this release, the /filter endpoint is now deprecated in favor of the new, faster, and more robust /search endpoint. |
0 commit comments