Simple email application for Android. Original source code: https://framagit.org/dystopia-project/simple-email
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

270 lines
10 KiB

  1. # JavaScript API
  2. ## Usage
  3. ```js
  4. const semanticRelease = require('semantic-release');
  5. const {WritableStreamBuffer} = require('stream-buffers');
  6. const stdoutBuffer = WritableStreamBuffer();
  7. const stderrBuffer = WritableStreamBuffer();
  8. try {
  9. const result = await semanticRelease({
  10. // Core options
  11. branch: 'master',
  12. repositoryUrl: 'https://github.com/me/my-package.git',
  13. // Shareable config
  14. extends: 'my-shareable-config',
  15. // Plugin options
  16. githubUrl: 'https://my-ghe.com',
  17. githubApiPathPrefix: '/api-prefix'
  18. }, {
  19. // Run semantic-release from `/path/to/git/repo/root` without having to change local process `cwd` with `process.chdir()`
  20. cwd: '/path/to/git/repo/root',
  21. // Pass the variable `MY_ENV_VAR` to semantic-release without having to modify the local `process.env`
  22. env: {...process.env, MY_ENV_VAR: 'MY_ENV_VAR_VALUE'},
  23. // Store stdout and stderr to use later instead of writing to `process.stdout` and `process.stderr`
  24. stdout: stdoutBuffer,
  25. stderr: stderrBuffer
  26. });
  27. if (result) {
  28. const {lastRelease, commits, nextRelease, releases} = result;
  29. console.log(`Published ${nextRelease.type} release version ${nextRelease.version} containing ${commits.length} commits.`);
  30. if (lastRelease.version) {
  31. console.log(`The last release was "${lastRelease.version}".`);
  32. }
  33. for (const release of releases) {
  34. console.log(`The release was published with plugin "${pluginName}".`);
  35. }
  36. } else {
  37. console.log('No release published.');
  38. }
  39. // Get stdout and stderr content
  40. const logs = stdoutBuffer.getContentsAsString('utf8');
  41. const errors = stderrBuffer.getContentsAsString('utf8');
  42. } catch (err) {
  43. console.error('The automated release failed with %O', err)
  44. }
  45. ```
  46. ## API
  47. ### semanticRelease([options], [config]) => Promise<Result>
  48. Run **semantic-release** and returns a `Promise` that resolves to a [Result](#result) object.
  49. #### options
  50. Type: `Object`
  51. **semantic-release** options.
  52. Can be used to set any [core option](../usage/configuration.md#configuration) or [plugin options](../usage/plugins.md#configuration).
  53. Each option, will take precedence over options configured in the [configuration file](../usage/configuration.md#configuration) and [shareable configurations](../usage/configuration.md#extends).
  54. #### config
  55. Type: `Object`
  56. **semantic-release** configuration specific for API usage.
  57. ##### cwd
  58. Type: `String`<br>
  59. Default: `process.cwd()`
  60. The current working directory to use. It should be configured to the root of the Git repository to release from.
  61. It allows to run **semantic-release** from a specific path without having to change the local process `cwd` with `process.chdir()`.
  62. ##### env
  63. Type: `Object`<br>
  64. Default: `process.env`
  65. The environment variables to use.
  66. It allows to run **semantic-release** with specific environment variables without having to modify the local `process.env`.
  67. ##### stdout
  68. Type: [`stream.Writable`](https://nodejs.org/api/stream.html#stream_writable_streams)<br>
  69. Default: `process.stdout`
  70. The [writable stream](https://nodejs.org/api/stream.html#stream_writable_streams) used to log information.
  71. It allows to configure **semantic-release** to write logs to a specific stream rather than the local `process.stdout`.
  72. ##### stderr
  73. Type: [`stream.Writable`](https://nodejs.org/api/stream.html#stream_writable_streams)<br>
  74. Default: `process.stderr`
  75. The [writable stream](https://nodejs.org/api/stream.html#stream_writable_streams) used to log errors.
  76. It allows to configure **semantic-release** to write errors to a specific stream rather than the local `process.stderr`.
  77. ### Result
  78. Type: `Object` `Boolean`<br>
  79. And object with [`lastRelease`](#lastrelease), [`nextRelease`](#nextrelease), [`commits`](#commits) and [`releases`](#releases) if a release is published or `false` if no release was published.
  80. #### lastRelease
  81. Type: `Object`
  82. Information related to the last release found:
  83. | Name | Type | Description |
  84. |---------|----------|----------------------------------------------------------------------------------------------------|
  85. | version | `String` | The version of the last release. |
  86. | gitHead | `String` | The sha of the last commit being part of the last release. |
  87. | gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release. |
  88. **Notes**: If no previous release is found, `lastRelease` will be an empty `Object`.
  89. Example:
  90. ```js
  91. {
  92. gitHead: 'da39a3ee5e6b4b0d3255bfef95601890afd80709',
  93. version: '1.0.0',
  94. gitTag: 'v1.0.0',
  95. }
  96. ```
  97. #### commits
  98. Type: `Array<Object>`
  99. The list of commit included in the new release.<br>
  100. Each commit object has the following properties:
  101. | Name | Type | Description |
  102. |-----------------|----------|-------------------------------------------------|
  103. | commit | `Object` | The commit abbreviated and full hash. |
  104. | commit.long | `String` | The commit hash. |
  105. | commit.short | `String` | The commit abbreviated hash. |
  106. | tree | `Object` | The commit abbreviated and full tree hash. |
  107. | tree.long | `String` | The commit tree hash. |
  108. | tree.short | `String` | The commit abbreviated tree hash. |
  109. | author | `Object` | The commit author information. |
  110. | author.name | `String` | The commit author name. |
  111. | author.email | `String` | The commit author email. |
  112. | author.short | `String` | The commit author date. |
  113. | committer | `Object` | The committer information. |
  114. | committer.name | `String` | The committer name. |
  115. | committer.email | `String` | The committer email. |
  116. | committer.short | `String` | The committer date. |
  117. | subject | `String` | The commit subject. |
  118. | body | `String` | The commit body. |
  119. | message | `String` | The commit full message (`subject` and `body`). |
  120. | hash | `String` | The commit hash. |
  121. | committerDate | `String` | The committer date. |
  122. Example:
  123. ```js
  124. [
  125. {
  126. commit: {
  127. long: '68eb2c4d778050b0701136ca129f837d7ed494d2',
  128. short: '68eb2c4'
  129. },
  130. tree: {
  131. long: '7ab515d12bd2cf431745511ac4ee13fed15ab578',
  132. short: '7ab515d'
  133. },
  134. author: {
  135. name: 'Me',
  136. email: 'me@email.com',
  137. date: 2018-07-22T20:52:44.000Z
  138. },
  139. committer: {
  140. name: 'Me',
  141. email: 'me@email.com',
  142. date: 2018-07-22T20:52:44.000Z
  143. },
  144. subject: 'feat: a new feature',
  145. body: 'Description of the new feature',
  146. hash: '68eb2c4d778050b0701136ca129f837d7ed494d2',
  147. message: 'feat: a new feature\n\nDescription of the new feature',
  148. committerDate: 2018-07-22T20:52:44.000Z
  149. }
  150. ]
  151. ```
  152. #### nextRelease
  153. Type: `Object`
  154. Information related to the newly published release:
  155. | Name | Type | Description |
  156. |---------|----------|---------------------------------------------------------------------------------------------------|
  157. | type | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`). |
  158. | version | `String` | The version of the new release. |
  159. | gitHead | `String` | The sha of the last commit being part of the new release. |
  160. | gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the new release. |
  161. | notes | `String` | The release notes for the new release. |
  162. Example:
  163. ```js
  164. {
  165. type: 'minor',
  166. gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2',
  167. version: '1.1.0',
  168. gitTag: 'v1.1.0',
  169. notes: 'Release notes for version 1.1.0...',
  170. }
  171. ```
  172. #### releases
  173. Type: `Array<Object>`
  174. The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).<br>
  175. Each release object has the following properties:
  176. | Name | Type | Description |
  177. |------------|----------|-----------------------------------------------------------------------------------------------|
  178. | name | `String` | **Optional.** The release name, only if set by the corresponding `publish` plugin. |
  179. | url | `String` | **Optional.** The release URL, only if set by the corresponding `publish` plugin. |
  180. | type | `String` | The [semver](https://semver.org) type of the release (`patch`, `minor` or `major`). |
  181. | version | `String` | The version of the release. |
  182. | gitHead | `String` | The sha of the last commit being part of the release. |
  183. | gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the release. |
  184. | notes | `String` | The release notes for the release. |
  185. | pluginName | `String` | The name of the plugin that published the release. |
  186. Example:
  187. ```js
  188. [
  189. {
  190. name: 'GitHub release',
  191. url: 'https://github.com/me/my-package/releases/tag/v1.1.0',
  192. type: 'minor',
  193. gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2',
  194. version: '1.1.0',
  195. gitTag: 'v1.1.0',
  196. notes: 'Release notes for version 1.1.0...',
  197. pluginName: '@semantic-release/github'
  198. },
  199. {
  200. name: 'npm package (@latest dist-tag)',
  201. url: 'https://www.npmjs.com/package/my-package',
  202. type: 'minor',
  203. gitHead: '68eb2c4d778050b0701136ca129f837d7ed494d2',
  204. version: '1.1.0',
  205. gitTag: 'v1.1.0',
  206. notes: 'Release notes for version 1.1.0...',
  207. pluginName: '@semantic-release/npm'
  208. }
  209. ]
  210. ```