Fincer
/
simple-email
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 0 Wiki Activity
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.
1588 Commits
1 Branch
22 KiB
Tree: 6407201467
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '6407201467'
${ noResults }
simple-email/node_modules/semantic-release/docs/support/FAQ.md

245 lines
18 KiB
Raw Normal View History

style: reformat indent
6 years ago
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
 
  1. # Frequently Asked Questions

  2. 

  3. ## Why is the `package.json`’s version not updated in my repository?

  4. 

  5. **semantic-release** takes care of updating the `package.json`’s version before publishing to [npm](https://www.npmjs.com).
  6. 

  7. By default, only the published package will contains the version, which is the only place where it is *really* required, but the updated `package.json` will not be pushed to the Git repository
  8. 

  9. However, the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used to push the updated `package.json` as well as other files to the Git repository.
  10. 

  11. ## How can I use a npm build script that requires the `package.json`’s version ?

  12. 

  13. The `package.json`’s version will be updated by the `semantic-release` command just before publishing to [npm](https://www.npmjs.com), therefore it won't be available for scripts ran before the `semantic-release` command.
  14. 

  15. As the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin uses the [npm CLI](https://docs.npmjs.com/cli/npm) to update the `package.json` version and publish the package, all [npm hook scripts](https://docs.npmjs.com/misc/scripts#description) will be executed.
  16. 

  17. You can run your build script in:
  18. - the `prepublishOnly` or `prepack` hook so it will be executed during the `publish` step of `@semantic-release/npm`
  19. - the `postversion` hook so it will be executed during the `prepare` step of `@semantic-release/npm`, which allow for example to update files before committing them with the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin
  20. 

  21. If using npm hook scripts is not possible, and alternative solution is to [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin to run your script in the `prepare` step:
  22. ```json
  23. {
  24.   "plugins": [
  25.     "@semantic-release/commit-analyzer",
  26.     "@semantic-release/release-notes-generator",
  27.     "@semantic-release/npm",
  28.     ["@semantic-release/exec", {
  29.       "prepareCmd": "./my-build-script.sh ${nextRelease.version}",
  30.     }],
  31.   ]
  32. }
  33. ```
  34. 

  35. ## Is there a way to preview which version would currently get published?

  36. 

  37. Yes with the [dry-run options](../usage/configuration.md#dryrun) which prints to the console the next version to be published and the release notes.
  38. 

  39. ## Can I use semantic-release with Yarn?

  40. 

  41. If you are using a [local](../usage/installation.md#local-installation) **semantic-release** installation and run multiple CI jobs with different versions, the `yarn install` command will fail on jobs running with Node < 8 as **semantic-release** requires [Node >= 8.3](#why-does-semantic-release-require-node-version--83) and specifies it in its `package.json`s [`engines`](https://docs.npmjs.com/files/package.json#engines) key.
  42. 

  43. The recommended solution is to use the [Yarn](https://yarnpkg.com) [--ignore-engines](https://yarnpkg.com/en/docs/cli/install#toc-yarn-install-ignore-engines) option to install the project dependencies on the CI environment, so Yarn will ignore the **semantic-release**'s `engines` key:
  44. 

  45. ```bash
  46. $ yarn install --ignore-engines
  47. ```
  48. 

  49. **Note**: Several CI services use Yarn by default if your repository contains a `yarn.lock` file. So you should override the install step to specify `yarn install --ignore-engines`.
  50. 

  51. Alternatively you can use a [global](../usage/installation.md#global-installation) **semantic-release** installation and make sure to install and run the `semantic-release` command only in a CI jobs running with Node >= 8.3.
  52. 

  53. If your CI environment provides [nvm](https://github.com/creationix/nvm) you can switch to Node 8 before installing and running the `semantic-release` command:
  54. 

  55. ```bash
  56. $ nvm install 8 && yarn global add semantic-release && semantic-release
  57. ```
  58. 

  59. See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
  60. 

  61. As `semantic-release` is recommended to be executed with [`npx`](https://www.npmjs.com/package/npx) an alternative is required for usage with Yarn. Even though it is possible to install npx with Yarn, it's not recommended. Yarn and npx would be using different cache locations.
  62. 

  63. For [local installation](../usage/installation.md#local-installation) replace
  64. `npx semantic-release` with `yarn run semantic-release`.
  65. 

  66. For [global installation](../usage/installation.md#global-installation) replace
  67. `npx semantic-release` with `yarn global add semantic-release && semantic-release`.
  68. 

  69. ## Can I use semantic-release to publish non-JavaScript packages?

  70. 

  71. Yes, **semantic-release** is a Node CLI application but it can be used to publish any type of packages.
  72. 

  73. To publish a non-Node package (without a `package.json`) you would need to:
  74. - Use a [global](../usage/installation.md#global-installation) **semantic-release** installation
  75. - Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or rc file](../usage/configuration.md#configuration)
  76. - Make sure your CI job executing the `semantic-release` command has access to [Node >= 8](#why-does-semantic-release-require-node-version--83) to execute the `semantic-release` command
  77. 

  78. See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
  79. 

  80. In addition you will need to configure the **semantic-release** [plugins](../usage/plugins.md#plugins) to disable the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin which is used by default and use a plugin for your project type.
  81. 

  82. If there is no specific plugin for your project type you can use the [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin to publish the release with a shell command.
  83. 

  84. Here is a basic example to create [GitHub releases](https://help.github.com/articles/about-releases) and use a shell command to publish:
  85. 

  86. ```json
  87. {
  88.   "plugins": [
  89.     "@semantic-release/commit-analyzer",
  90.     "@semantic-release/release-notes-generator",
  91.     "@semantic-release/github",
  92.     ["@semantic-release/exec", {
  93.       "prepareCmd" : "set-version ${nextRelease.version}",
  94.       "publishCmd" : "publish-package"
  95.       }]
  96.   ]
  97. }
  98. ```
  99. 

  100. **Note**: This is a theoretical example where the command `set-version` update the project version with the value passed as its first argument and `publish-package` publishes the package to a registry.
  101. 

  102. See the [package managers and languages recipes](../recipes/README.md#package-managers-and-languages) for more details on specific project types.
  103. 

  104. ## Can I use semantic-release with any CI service?

  105. 

  106. Yes, **semantic-release** can be used with any CI service, as long as it provides:
  107. - A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables
  108. - A way to guarantee that the `semantic-release` command is [executed only after all the tests of all the jobs in the CI build pass](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
  109. 

  110. See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
  111. 

  112. ## Can I run semantic-release on my local machine rather than on a CI server?

  113. 

  114. Yes, you can by explicitly setting the [`--no-ci` CLI option](../usage/configuration.md#ci) option. You will also have to set the required [authentication](../usage/ci-configuration.md#authentication) via environment variables on your local machine, for example:
  115. 

  116. ```bash
  117. $ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci
  118. ```
  119. 

  120. However this is not the recommended approach, as running unit and integration tests on an independent machine before publishing software is a crucial part of the release workflow.
  121. 

  122. ## Can I use semantic-release with GitLab?

  123. 

  124. Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration.
  125. 

  126. See the [GitLab CI recipes](../recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
  127. 

  128. ## Can I use semantic-release with any Git hosted environment?

  129. 

  130. By default **semantic-release** uses the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin to publish a [GitHub release](https://help.github.com/articles/about-releases). For other Git hosted environment the  [`@semantic-release/git`](https://github.com/semantic-release/git) and [`@semantic-release/changelog`](https://github.com/semantic-release/changelog) plugins can be used via [plugins configuration](../usage/plugins.md).
  131. 

  132. See the [`@semantic-release/git`](https://github.com/semantic-release/git#semantic-releasegit) [`@semantic-release/changelog`](https://github.com/semantic-release/changelog#semantic-releasechangelog) plugins documentation for more details.
  133. 

  134. ## Can I skip the release to the npm registry?

  135. 

  136. Yes, the publishing to the npm registry can be disabled with the [`npmPublish`](https://github.com/semantic-release/npm#options) option of the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin. In addition the [`tarballDir`](https://github.com/semantic-release/npm#options) option allow to generate the package tarball in order to publish it to your repository with the [`@semantic-release/git`](https://github.com/semantic-release/git) or to a [GitHub release](https://help.github.com/articles/about-releases) with the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin.
  137. 

  138. See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#semantic-releasenpm) plugin documentation for more details.
  139. 

  140. ## How can I revert a release?

  141. 

  142. If you have introduced a breaking bug in a release you have 2 options:
  143. - If you have a fix immediately ready, commit and push it (or merge it via a pull request) to the release branch
  144. - Otherwise [revert the commit](https://git-scm.com/docs/git-revert) that introduced the bug and push the revert commit (or merge it via a pull request) to the release branch
  145. 

  146. In both cases **semantic-release** will publish a new release, so your package users' will get the fixed/reverted version.
  147. 

  148. Depending on the package manager you are using, you might be able to un-publish or deprecate a release, in order to prevent users to download it by accident. For example npm allows you to [un-publish](https://docs.npmjs.com/cli/unpublish) in [next 72 hours](https://www.npmjs.com/policies/unpublish) after releasing or to [deprecate](https://docs.npmjs.com/cli/deprecate) a release.
  149. 

  150. In any case **do not remove the Git tag associated with the buggy version**, otherwise **semantic-release** will later try to republish that version. Publishing a version after un-publishing is not supported by most package managers.
  151. 

  152. **Note**: If you are using the default [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) be aware that it uses a different revert commit format than the standard one created by [git revert](https://git-scm.com/docs/git-revert), contrary to what is [claimed in the  convention](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). Therefore, if you revert a commit with [`git revert`](https://git-scm.com/docs/git-revert), use the [`--edit` option](https://git-scm.com/docs/git-revert#git-revert---edit) to format the message according to the [Angular revert commit message format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). See [conventional-changelog/conventional-changelog#348](https://github.com/conventional-changelog/conventional-changelog/issues/348) for more details.
  153. 

  154. ## Can I use `.npmrc` options?

  155. 

  156. Yes, all the [npm configuration options](https://docs.npmjs.com/misc/config) are supported via the [`.npmrc`](https://docs.npmjs.com/files/npmrc) file at the root of your repository.
  157. 

  158. See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#npm-configuration) plugin documentation for more details.
  159. 

  160. ## How can I set the access level of the published npm package?

  161. 

  162. The [npm `access` option](https://docs.npmjs.com/misc/config#access) can be set in the [`.npmrc`](https://docs.npmjs.com/files/npmrc) file at the root of your repository:
  163. 

  164. ```rc
  165. access=public
  166. ```
  167. 

  168. Or with the `publishConfig.access` key in your project's `package.json`:
  169. 

  170. ```json
  171. {
  172.   "publishConfig": {
  173.     "access": "public"
  174.   }
  175. }
  176. ```
  177. 

  178. ## Can I use semantic-release to publish a package on Artifactory?

  179. 

  180. Any npm compatible registry is supported with the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin. For Artifactory versions prior to 5.4, the legacy authentication has to be used (with `NPM_USERNAME`, `NPM_PASSWORD` and `NPM_EMAIL` [environment variables](https://github.com/semantic-release/npm#environment-variables)).
  181. 

  182. See [npm registry authentication](https://github.com/semantic-release/npm#npm-registry-authentication) for more details.
  183. 

  184. See [Artifactory - npm Registry](https://www.jfrog.com/confluence/display/RTF/Npm+Registry#NpmRegistry-AuthenticatingthenpmClient) documentation for Artifactiry configuration.
  185. 

  186. ## Can I manually trigger the release of a specific version?

  187. 

  188. You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a *specific* version release, because this is the whole point of semantic-release.
  189. 

  190. ## Can I exclude commits from the analysis?

  191. 

  192. Yes, every commits that contains `[skip release]` or `[release skip]` in their message will be excluded from the commit analysis and won't participate in the release type determination.
  193. 

  194. ## How can I change the type of commits that trigger a release?

  195. 

  196. By default **semantic-release** uses the [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) and triggers releases based on the following rules:
  197. 

  198. | Commit                      | Release type               |
  199. |-----------------------------|----------------------------|
  200. | Commit with breaking change | ~~Major~~ Breaking release |
  201. | Commit with type `feat`     | ~~Minor~~ Feature release  |
  202. | Commit with type `fix`      | Patch release              |
  203. | Commit with type `perf`     | Patch release              |
  204. 

  205. See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#npm-configuration) plugin documentation for more details.
  206. 

  207. This is fully customizable with the [`@semantic-release/commit-analyzer`](https://github.com/semantic-release/commit-analyzer) plugin's [`release-rules` option](https://github.com/semantic-release/commit-analyzer#release-rules).
  208. 

  209. ## Is it *really* a good idea to release on every push?

  210. 

  211. It is indeed a great idea because it *forces* you to follow best practices. If you don’t feel comfortable releasing every feature or fix on your `master` you might not treat your `master` branch as intended.
  212. 

  213. From [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/index.html):
  214. 

  215. > Branching is a core concept in Git, and the entire GitHub Flow is based upon it. There's only one rule: anything in the master branch is always deployable.

  216. 

  217. If you need more control over the timing of releases, see [Triggering a release](../../README.md#triggering-a-release) for different options.
  218. 

  219. **Note**: Only the codebase changes altering the published package will trigger a release (for example new features, bug fixes or performance improvements would trigger a release while refactoring or changing code style would not). See [How can I change the type of commits that trigger a release?](#how-can-i-change-the-type-of-commits-that-trigger-a-release) for more details.
  220. 

  221. ## Can I set the initial release version of my package to `0.0.1`?

  222. 

  223. This is not supported by **semantic-release** as it's not considered a good practice, mostly because [Semantic Versioning](https://semver.org) rules applies differently to major version zero.
  224. 

  225. In early development phase when your package is not ready for production yet we recommend to publish releases on a distribution channel (for example npm’s [dist-tags](https://docs.npmjs.com/cli/dist-tag)) or to develop on a `dev` branch and merge it to `master` periodically. See [Triggering a release](../../README.md#triggering-a-release) for more details on those solutions.
  226. 

  227. See [“Introduction to SemVer” - Irina Gebauer](https://blog.greenkeeper.io/introduction-to-semver-d272990c44f2) for more details on [Semantic Versioning](https://semver.org) and the recommendation to start at version `1.0.0`.
  228. 

  229. ## Can I trust semantic-release with my releases?

  230. 

  231. **semantic-release** has a full unit and integration test suite that tests `npm` publishes against the [npm-registry-couchapp](https://github.com/npm/npm-registry-couchapp).
  232. 

  233. In addition the [verify conditions step](../../README.md#release-steps) verifies that all necessary conditions for proceeding with a release are met, and a new release will be performed [only if all your tests pass](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
  234. 

  235. ## Why does semantic-release require Node version >= 8.3?

  236. 

  237. **semantic-release** is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which **requires Node version 8.3 or higher**.
  238. 

  239. See [Node version requirement](../support/node-version.md#node-version-requirement) for more details and solutions.
  240. 

  241. ## What is npx?

  242. 

  243. [`npx`](https://www.npmjs.com/package/npx) – short for "npm exec" – is a CLI to find and execute npm binaries within the local `node_modules` folder or in the $PATH. If a binary can't be located npx will download the required package and execute it from its cache location.
  244. The tool is bundled with [npm](https://www.npmjs.com/package/npm) >= 5.2, or can be installed via `npm install -g npx`.
  245. For more details and motivation read the [introductory blog post](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) by [@zkat](https://github.com/zkat).