fix: revert to previous documentation folder structure (#18127)
This commit is contained in:
Michelle Tilley
GitHub
parent
c278043511
commit
4808f30538
8 changed files with 19 additions and 19 deletions
|
|
@ -30,7 +30,7 @@ As of version 2.0 Electron [follows `semver`](https://semver.org).
|
|||
For most applications, and using any recent version of npm,
|
||||
running `$ npm install electron` will do the right thing.
|
||||
|
||||
The version update process is detailed explicitly in our [Versioning Doc](../electron-versioning.md).
|
||||
The version update process is detailed explicitly in our [Versioning Doc](electron-versioning.md).
|
||||
|
||||
### LTS
|
||||
|
||||
|
|
|
|||
2
docs/tutorial/app-feedback-program.md
Normal file
2
docs/tutorial/app-feedback-program.md
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
# Electron App Feedback Program
|
||||
Electron is working on building a streamlined release process and having faster releases. To help with that, we have the App Feedback Program for large-scale Electron apps to test our beta releases and report app-specific issues to the Electron team. We use this program to help us prioritize work and get applications upgraded to the next stable release as soon as possible. There are a few requirements we expect from participants, such as attending short, online weekly check-ins. Please visit the [blog post](https://electronjs.org/blog/app-feedback-program) for details and sign-up.
|
||||
50
docs/tutorial/electron-timelines.md
Normal file
50
docs/tutorial/electron-timelines.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Electron Release Timelines
|
||||
### Notes:
|
||||
* The `-beta.1` and `stable` dates are our *concrete* release dates.
|
||||
* We strive for weekly beta releases, however we often release more betas than scheduled.
|
||||
* All dates are our goals but there may be reasons for adjusting the stable deadline, such as security bugs.
|
||||
|
||||
## 5.0.0 Release Schedule
|
||||
*Includes: Chromium M73 and Node v12.0*
|
||||
|
||||
Take a look at 5.0.0 Timeline [blog post](https://electronjs.org/blog/electron-5-0-timeline) for info about publicizing our release dates.
|
||||
|
||||
| Date/Week Of | Release | Comments |
|
||||
| --------------- | ------------ | -------------- |
|
||||
| Tue, 2019-Jan-22 | 5.0.0-beta.1 |🔥 |
|
||||
| Tue, 2019-Jan-29 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Feb-05 | 5.0.0-beta.x |Last Date to Join [AFP](https://electronjs.org/blog/app-feedback-program)|
|
||||
| Tue, 2019-Feb-12 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Feb-19 | none | Maintainers Summit |
|
||||
| Tue, 2019-Feb-26 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Mar-05 | 5.0.0-beta.x | halfway mark |
|
||||
| Tue, 2019-Mar-12 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Mar-19 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Mar-26 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Apr-02 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Apr-09 | 5.0.0-beta.x ||
|
||||
| Tue, 2019-Apr-16 | none | quiet period - stable prep |
|
||||
| Tue, 2019-Apr-23 | 5.0.0 |✨stable ✨|
|
||||
|
||||
## 6.0.0 Release Schedule
|
||||
*Includes: Chromium M76 and Node v12.0*
|
||||
|
||||
| Date/Week Of | Release | Comments |
|
||||
| --------------- | ------------ | -------------- |
|
||||
| Tue, 2019-Apr-30 | 6.0.0-beta.1 | 🔥 |
|
||||
| Tue, 2019-May-07 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-May-14 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-May-21 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-May-28 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jun-04 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jun-11 | 6.0.0-beta.x | halfway mark |
|
||||
| Tue, 2019-Jun-18 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jun-25 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jul-02 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jul-09 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jul-16 | 6.0.0-beta.x | |
|
||||
| Tue, 2019-Jul-23 | 6.0.0-beta.x | 🚧 quiet period - stable prep 🚧 |
|
||||
| Tue, 2019-Jul-30 | 6.0.0 | ✨ stable ✨ |
|
||||
|
||||
## 7.0.0 Release Schedule
|
||||
TBD
|
||||
150
docs/tutorial/electron-versioning.md
Normal file
150
docs/tutorial/electron-versioning.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
# Electron Versioning
|
||||
|
||||
> A detailed look at our versioning policy and implementation.
|
||||
|
||||
As of version 2.0.0, Electron follows [semver](#semver). The following command will install the most recent stable build of Electron:
|
||||
|
||||
```sh
|
||||
npm install --save-dev electron
|
||||
```
|
||||
|
||||
To update an existing project to use the latest stable version:
|
||||
|
||||
```sh
|
||||
npm install --save-dev electron@latest
|
||||
```
|
||||
|
||||
## Version 1.x
|
||||
|
||||
Electron versions *< 2.0* did not conform to the [semver](http://semver.org) spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
|
||||
|
||||
Here is an example of the 1.x strategy:
|
||||
|
||||
|
||||
|
||||
An app developed with `1.8.1` cannot take the `1.8.3` bug fix without either absorbing the `1.8.2` feature, or by backporting the fix and maintaining a new release line.
|
||||
|
||||
## Version 2.0 and Beyond
|
||||
|
||||
There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
|
||||
|
||||
1. Strict use of semver
|
||||
2. Introduction of semver-compliant `-beta` tags
|
||||
3. Introduction of [conventional commit messages](https://conventionalcommits.org/)
|
||||
4. Well-defined stabilization branches
|
||||
5. The `master` branch is versionless; only stabilization branches contain version information
|
||||
|
||||
We will cover in detail how git branching works, how npm tagging works, what developers should expect to see, and how one can backport changes.
|
||||
|
||||
# semver
|
||||
|
||||
From 2.0 onward, Electron will follow semver.
|
||||
|
||||
Below is a table explicitly mapping types of changes to their corresponding category of semver (e.g. Major, Minor, Patch).
|
||||
|
||||
| Major Version Increments | Minor Version Increments | Patch Version Increments |
|
||||
| ------------------------------- | ---------------------------------- | ----------------------------- |
|
||||
| Electron breaking API changes | Electron non-breaking API changes | Electron bug fixes |
|
||||
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
|
||||
| Chromium version updates | | fix-related chromium patches |
|
||||
|
||||
|
||||
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
|
||||
|
||||
# Stabilization Branches
|
||||
|
||||
Stabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
|
||||
|
||||
|
||||
|
||||
Stabilization branches are always either **major** or **minor** version lines, and named against the following template `$MAJOR-$MINOR-x` e.g. `2-0-x`.
|
||||
|
||||
We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.
|
||||
|
||||
|
||||
Older lines will not be supported by GitHub, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
|
||||
|
||||
# Beta Releases and Bug Fixes
|
||||
|
||||
Developers want to know which releases are _safe_ to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in `package.json` :
|
||||
|
||||
* Use `~2.0.0` to admit only stability or security related fixes to your `2.0.0` release.
|
||||
* Use `^2.0.0` to admit non-breaking _reasonably stable_ feature work as well as security and bug fixes.
|
||||
|
||||
What’s important about the second point is that apps using `^` should still be able to expect a reasonable level of stability. To accomplish this, semver allows for a _pre-release identifier_ to indicate a particular version is not yet _safe_ or _stable_.
|
||||
|
||||
Whatever you choose, you will periodically have to bump the version in your `package.json` as breaking changes are a fact of Chromium life.
|
||||
|
||||
The process is as follows:
|
||||
|
||||
1. All new major and minor releases lines begin with a beta series indicated by semver prerelease tags of `beta.N`, e.g. `2.0.0-beta.1`. After the first beta, subsequent beta releases must meet all of the following conditions:
|
||||
1. The change is backwards API-compatible (deprecations are allowed)
|
||||
2. The risk to meeting our stability timeline must be low.
|
||||
2. If allowed changes need to be made once a release is beta, they are applied and the prerelease tag is incremented, e.g. `2.0.0-beta.2`.
|
||||
3. If a particular beta release is _generally regarded_ as stable, it will be re-released as a stable build, changing only the version information. e.g. `2.0.0`. After the first stable, all changes must be backwards-compatible bug or security fixes.
|
||||
4. If future bug fixes or security patches need to be made once a release is stable, they are applied and the _patch_ version is incremented
|
||||
e.g. `2.0.1`.
|
||||
|
||||
Specifically, the above means:
|
||||
|
||||
1. Admitting non-breaking-API changes early in the beta cycle is okay, even if those changes have the potential to cause moderate side-affects
|
||||
2. Admitting feature-flagged changes, that do not otherwise alter existing code paths, at most points in the beta cycle is okay. Users can explicitly enable those flags in their apps.
|
||||
3. Admitting features of any sort very late in the beta cycle is 👎 without a very good reason.
|
||||
|
||||
For each major and minor bump, you should expect to see something like the following:
|
||||
|
||||
```text
|
||||
2.0.0-beta.1
|
||||
2.0.0-beta.2
|
||||
2.0.0-beta.3
|
||||
2.0.0
|
||||
2.0.1
|
||||
2.0.2
|
||||
```
|
||||
|
||||
An example lifecycle in pictures:
|
||||
|
||||
* A new release branch is created that includes the latest set of features. It is published as `2.0.0-beta.1`.
|
||||
|
||||
* A bug fix comes into master that can be backported to the release branch. The patch is applied, and a new beta is published as `2.0.0-beta.2`.
|
||||
|
||||
* The beta is considered _generally stable_ and it is published again as a non-beta under `2.0.0`.
|
||||
|
||||
* Later, a zero-day exploit is revealed and a fix is applied to master. We backport the fix to the `2-0-x` line and release `2.0.1`.
|
||||
|
||||
|
||||
A few examples of how various semver ranges will pick up new releases:
|
||||
|
||||
|
||||
|
||||
# Missing Features: Alphas
|
||||
Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
|
||||
|
||||
As a future consideration, we may introduce one or both of the following:
|
||||
|
||||
* alpha releases that have looser stability constraints to betas; for example it would be allowable to admit new features while a stability channel is in _alpha_
|
||||
|
||||
# Feature Flags
|
||||
Feature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or **soft branch** must have the following properties:
|
||||
|
||||
* it is enabled/disabled either at runtime, or build-time; we do not support the concept of a request-scoped feature flag
|
||||
* it completely segments new and old code paths; refactoring old code to support a new feature _violates_ the feature-flag contract
|
||||
* feature flags are eventually removed after the feature is released
|
||||
|
||||
# Semantic Commits
|
||||
|
||||
We seek to increase clarity at all levels of the update and releases process. Starting with `2.0.0` we will require pull requests adhere to the [Conventional Commits](https://conventionalcommits.org/) spec, which can be summarized as follows:
|
||||
|
||||
* Commits that would result in a semver **major** bump must start their body with `BREAKING CHANGE:`.
|
||||
* Commits that would result in a semver **minor** bump must start with `feat:`.
|
||||
* Commits that would result in a semver **patch** bump must start with `fix:`.
|
||||
|
||||
* We allow squashing of commits, provided that the squashed message adheres the the above message format.
|
||||
* It is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
|
||||
|
||||
# Versioned `master`
|
||||
|
||||
- The `master` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json`
|
||||
- Release branches are never merged back to master
|
||||
- Release branches _do_ contain the correct version in their `package.json`
|
||||
- As soon as a release branch is cut for a major, master must be bumped to the next major. I.e. `master` is always versioned as the next theoretical release branch
|
||||
94
docs/tutorial/support.md
Normal file
94
docs/tutorial/support.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# Electron Support
|
||||
|
||||
## Finding Support
|
||||
|
||||
If you have a security concern,
|
||||
please see the [security document](../../SECURITY.md).
|
||||
|
||||
If you're looking for programming help,
|
||||
for answers to questions,
|
||||
or to join in discussion with other developers who use Electron,
|
||||
you can interact with the community in these locations:
|
||||
- [`electron`](https://discuss.atom.io/c/electron) category on the Atom
|
||||
forums
|
||||
- `#atom-shell` channel on Freenode
|
||||
- [`Electron`](https://atom-slack.herokuapp.com) channel on Atom's Slack
|
||||
- [`electron-ru`](https://telegram.me/electron_ru) *(Russian)*
|
||||
- [`electron-br`](https://electron-br.slack.com) *(Brazilian Portuguese)*
|
||||
- [`electron-kr`](https://electron-kr.github.io/electron-kr) *(Korean)*
|
||||
- [`electron-jp`](https://electron-jp.slack.com) *(Japanese)*
|
||||
- [`electron-tr`](https://electron-tr.herokuapp.com) *(Turkish)*
|
||||
- [`electron-id`](https://electron-id.slack.com) *(Indonesia)*
|
||||
- [`electron-pl`](https://electronpl.github.io) *(Poland)*
|
||||
|
||||
If you'd like to contribute to Electron,
|
||||
see the [contributing document](../../CONTRIBUTING.md).
|
||||
|
||||
If you've found a bug in a [supported version](#supported-versions) of Electron,
|
||||
please report it with the [issue tracker](../development/issues.md).
|
||||
|
||||
[awesome-electron](https://github.com/sindresorhus/awesome-electron)
|
||||
is a community-maintained list of useful example apps,
|
||||
tools and resources.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
The latest three release branches are supported by the Electron team.
|
||||
For example, if the latest release is 2.0.x, then the 2-0-x series
|
||||
is supported, as are the two previous release series 1-7-x and 1-8-x.
|
||||
|
||||
When a release branch reaches the end of its support cycle, the series
|
||||
will be deprecated in NPM and a final end-of-support release will be
|
||||
made. This release will add a warning to inform that an unsupported
|
||||
version of Electron is in use.
|
||||
|
||||
These steps are to help app developers learn when a branch they're
|
||||
using becomes unsupported, but without being excessively intrusive
|
||||
to end users.
|
||||
|
||||
If an application has exceptional circumstances and needs to stay
|
||||
on an unsupported series of Electron, developers can silence the
|
||||
end-of-support warning by omitting the final release from the app's
|
||||
`package.json` `devDependencies`. For example, since the 1-6-x series
|
||||
ended with an end-of-support 1.6.18 release, developers could choose
|
||||
to stay in the 1-6-x series without warnings with `devDependency` of
|
||||
`"electron": 1.6.0 - 1.6.17`.
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
Following platforms are supported by Electron:
|
||||
|
||||
### macOS
|
||||
|
||||
Only 64bit binaries are provided for macOS, and the minimum macOS version
|
||||
supported is macOS 10.10 (Yosemite).
|
||||
|
||||
### Windows
|
||||
|
||||
Windows 7 and later are supported, older operating systems are not supported
|
||||
(and do not work).
|
||||
|
||||
Both `ia32` (`x86`) and `x64` (`amd64`) binaries are provided for Windows.
|
||||
Running Electron apps on Windows for ARM devices is possible by using the
|
||||
ia32 binary.
|
||||
|
||||
### Linux
|
||||
|
||||
The prebuilt `ia32` (`i686`) and `x64` (`amd64`) binaries of Electron are built on
|
||||
Ubuntu 12.04, the `armv7l` binary is built against ARM v7 with hard-float ABI and
|
||||
NEON for Debian Wheezy.
|
||||
|
||||
[Until the release of Electron 2.0][arm-breaking-change], Electron will also
|
||||
continue to release the `armv7l` binary with a simple `arm` suffix. Both binaries
|
||||
are identical.
|
||||
|
||||
Whether the prebuilt binary can run on a distribution depends on whether the
|
||||
distribution includes the libraries that Electron is linked to on the building
|
||||
platform, so only Ubuntu 12.04 is guaranteed to work, but following platforms
|
||||
are also verified to be able to run the prebuilt binaries of Electron:
|
||||
|
||||
* Ubuntu 12.04 and newer
|
||||
* Fedora 21
|
||||
* Debian 8
|
||||
|
||||
[arm-breaking-change]: https://github.com/electron/electron/blob/master/docs/api/breaking-changes.md#duplicate-arm-assets
|
||||
Loading…
Add table
Add a link
Reference in a new issue