Skip to content

Commit eff2e55

Browse files
authored
Update CONTRIBUTING.md
Include Release Notes Template
1 parent 537d35d commit eff2e55

File tree

1 file changed

+48
-3
lines changed

1 file changed

+48
-3
lines changed

CONTRIBUTING.md

+48-3
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
- [Autogenerated Documentation](#autodocs)
1414
- [Custom Documentation](#customdocs)
1515
- [Development Status](#status)
16+
- [Pubic Release Notes](#releasenotes)
1617

1718

1819
## Installation and Development<a name="install"></a>
@@ -210,9 +211,53 @@ One of the outstanding features of sphinx is its support for arbitrarily organiz
210211
materials such as tutorials, introductions, and other context-providing content. These items should
211212
be stored in source control under the `docs/source` directory in properly formatted `.rst` files.
212213

213-
214-
215214
## Development Status<a name="status"></a>
216215

217216
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

Comments
 (0)