From 28f419ec6074e97fd9196a8871bbb792216e4822 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 9 Apr 2023 03:51:40 -0700 Subject: [PATCH] Move developer guidelines to contributing #4665 (#4666) --- CHANGELOG.md | 104 ++++++++++++++++++ docs/source/cheatsheet.md | 2 +- docs/source/conf.py | 2 +- .../Quanta.pdf | Bin .../acceptance-tests.md | 0 .../accessibility-guidelines.md | 0 docs/source/contributing/branch-policy.md | 49 +++++++++ .../design-principles.md | 0 .../icons.md | 0 .../contributing.md => contributing/index.md} | 44 +++++++- .../language-features.md | 0 .../linting.md | 0 .../react.md | 0 .../redux.md | 0 .../routing.md | 0 .../style-guide.md | 0 .../testing.md | 0 .../typescript.md | 0 .../volto-core-addons.md | 0 docs/source/developer-guidelines/index.md | 38 ------- docs/source/index.md | 2 +- news/4666.documentation | 1 + 22 files changed, 195 insertions(+), 47 deletions(-) rename docs/source/{developer-guidelines => contributing}/Quanta.pdf (100%) rename docs/source/{developer-guidelines => contributing}/acceptance-tests.md (100%) rename docs/source/{developer-guidelines => contributing}/accessibility-guidelines.md (100%) create mode 100644 docs/source/contributing/branch-policy.md rename docs/source/{developer-guidelines => contributing}/design-principles.md (100%) rename docs/source/{developer-guidelines => contributing}/icons.md (100%) rename docs/source/{developer-guidelines/contributing.md => contributing/index.md} (65%) rename docs/source/{developer-guidelines => contributing}/language-features.md (100%) rename docs/source/{developer-guidelines => contributing}/linting.md (100%) rename docs/source/{developer-guidelines => contributing}/react.md (100%) rename docs/source/{developer-guidelines => contributing}/redux.md (100%) rename docs/source/{developer-guidelines => contributing}/routing.md (100%) rename docs/source/{developer-guidelines => contributing}/style-guide.md (100%) rename docs/source/{developer-guidelines => contributing}/testing.md (100%) rename docs/source/{developer-guidelines => contributing}/typescript.md (100%) rename docs/source/{developer-guidelines => contributing}/volto-core-addons.md (100%) delete mode 100644 docs/source/developer-guidelines/index.md create mode 100644 news/4666.documentation diff --git a/CHANGELOG.md b/CHANGELOG.md index 3994505681..2706cd0b50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,110 @@ +## 17.0.0-alpha.3 (2023-03-22) + +### Feature + +- Add Vale to CI for spell and style checks. @MAX-786 [#4423](https://github.com/plone/volto/issues/4423) + +### Bugfix + +- Fix Search is case sensitive in Block chooser @iRohitSingh [#4526](https://github.com/plone/volto/issues/4526) +- InternalURl helper method should incorporate externalRoutes settings into consideration. @iFlameing [#4559](https://github.com/plone/volto/issues/4559) +- Update message add-on control panel: remove 'buildout', update reference. @ksuess [#4574](https://github.com/plone/volto/issues/4574) + +### Documentation + +- Deleted duplicate import and fixed training URLs. @yahya-cloud [#4523](https://github.com/plone/volto/issues/4523) +- Fix grammar in PR #4542. @stevepiercy [#4555](https://github.com/plone/volto/issues/4555) +- Fix broken links at `ReactJS.org`. @stevepiercy [#4569](https://github.com/plone/volto/issues/4569) +- Fix video warnings and link errors. @stevepiercy [#4578](https://github.com/plone/volto/issues/4578) + + +## 17.0.0-alpha.2 (2023-03-15) + +### Breaking + +- Add custom CSS animation to hamburger menu. Removed `hamburgers` dependency. @danalvrz [#4433](https://github.com/plone/volto/issues/4433) +- Improve i18n script ordering of addons, so that addons can override translations from their dependencies. @davisagli [#4495](https://github.com/plone/volto/issues/4495) + +### Feature + +- Add option to hide empty listing blocks @ksuess [#4393](https://github.com/plone/volto/issues/4393) + +### Bugfix + +- Update build dependencies (razzle and react-dev-utils) @davisagli [#3997](https://github.com/plone/volto/issues/3997) +- Added block prop to BlockDataForm in the Edit component of ToC. If block is not passed, OnChangeBlock will be called with undefined block id. @tedw87 [#4110](https://github.com/plone/volto/issues/4110) +- Fix focus steal in Form @tedw87 [#4230](https://github.com/plone/volto/issues/4230) +- Fixed paste issue in Table Block and added cypress test for pasting text in Table Block. [#4301](https://github.com/plone/volto/issues/4301) +- Fixed i18n script to avoid overwriting translations with an empty msgstr @danalvrz [#4316](https://github.com/plone/volto/issues/4316) +- bugfix: conditionally render all delete items in confirm widget [#4336](https://github.com/plone/volto/issues/4336) +- Make the Site Setup control panel responsive for small screen devices. @lord2anil [#4484](https://github.com/plone/volto/issues/4484) +- The menu for the contents page was unresponsive on mobile devices. Fixed this by changing the menu overflow to scroll. @sudhanshu1309 [#4492](https://github.com/plone/volto/issues/4492) +- Make Drag and Drop list work with container-type inline-size. @robgietema [#4497](https://github.com/plone/volto/issues/4497) +- (fix): Paste button disappearing while coping from nested blocks @dobri1408 [#4505](https://github.com/plone/volto/issues/4505) +- Patch updates for some dependencies. @davisagli [#4520](https://github.com/plone/volto/issues/4520) +- Fix flaky Cypress test introduced in #4521 @sneridagh [#4522](https://github.com/plone/volto/issues/4522) + +### Documentation + +- Fix training urls @ksuess [#4502](https://github.com/plone/volto/issues/4502) +- Add upgrade guide for 4504 @sneridagh [#4542](https://github.com/plone/volto/issues/4542) + + +## 17.0.0-alpha.1 (2023-03-09) + +### Feature + +- - Add directive to cache stable resources in browser or intermediate server for 365 days by default directly in the SSR Express server, static resource that could change after a new deployment for 1 minute. @mamico [#2216](https://github.com/plone/volto/issues/2216) +- Use popperjs in BlockChooser, move the markup to the bottom of the body tag. @sneridagh [#4141](https://github.com/plone/volto/issues/4141) +- Improvements to the dev API proxy: + - Prefer RAZZLE_INTERNAL_API_PATH over RAZZLE_API_PATH as the target of the proxy. + The target of the API proxy is now always logged on startup, even in production mode. + - Support proxying to a backend served over https. For this configuration it + might be necessary to set RAZZLE_DEV_PROXY_INSECURE=1 if the backend + certificate can't be verified. + + [davisagli] [#4434](https://github.com/plone/volto/issues/4434) + +### Bugfix + +- fix: newsitem and event views wrapper classNames @nzambello [#4443](https://github.com/plone/volto/issues/4443) +- Fix weird GHA failure on config option not supported @sneridagh [#4466](https://github.com/plone/volto/issues/4466) +- Fix history view dropdown for first entry, showing 'Revert to this version option' always @sneridagh [#4471](https://github.com/plone/volto/issues/4471) +- Fix order of row of long table in edit and view mode @iFlameing [#4473](https://github.com/plone/volto/issues/4473) +- Improve flaky test in autofocus Cypress tests @sneridagh [#4475](https://github.com/plone/volto/issues/4475) + +### Documentation + +- Complete teaser docs, add new section in `Blocks`: `Core Blocks developers notes` @sneridagh [#4461](https://github.com/plone/volto/issues/4461) +- Change from links to inline literals in `CHANGELOG.md` to fix linkcheckbroken. @stevepiercy [#4470](https://github.com/plone/volto/issues/4470) + + +## 17.0.0-alpha.0 (2023-03-04) + +### Breaking + +- Volto 17 drops support for NodeJS 14, and adds support for NodeJS 18. + Please see the [upgrade guide](https://6.docs.plone.org/volto/upgrade-guide/index.html) + for more information. + + Volto 17 now uses Webpack 5. [#4086](https://github.com/plone/volto/issues/4086) + +### Internal + +- Add HI-ERN website to "Volto in Production" section in README @steffenri [#4172](https://github.com/plone/volto/issues/4172) + +### Documentation + +- Add a new Volto site to the README @erral [#4158](https://github.com/plone/volto/issues/4158), [#4170](https://github.com/plone/volto/issues/4170) +- Add new websites Lanku and UEU + [erral] [#4310](https://github.com/plone/volto/issues/4310) +- Fix English and MyST grammar and syntax from PR #4285 @stevepiercy [#4331](https://github.com/plone/volto/issues/4331) +- Use a universal static path for both documentation and volto repos. @stevepiercy [#4376](https://github.com/plone/volto/issues/4376) + + ## 16.19.0 (2023-04-04) ### Feature diff --git a/docs/source/cheatsheet.md b/docs/source/cheatsheet.md index dc7eb80d88..f7b8601d7d 100644 --- a/docs/source/cheatsheet.md +++ b/docs/source/cheatsheet.md @@ -14,7 +14,7 @@ myst: # Cheatsheet ```{seealso} -{doc}`plone:contributing/myst-reference` +{doc}`plone:contributing/documentation/myst-reference` ``` diff --git a/docs/source/conf.py b/docs/source/conf.py index 1421636d3f..679833e9a9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -119,7 +119,7 @@ "spelling_wordlist.txt", "**/CHANGES.rst", "**/LICENSE.rst", - "developer-guidelines/branch-policy.md", + "contributing/branch-policy.md", ] html_extra_path = [ diff --git a/docs/source/developer-guidelines/Quanta.pdf b/docs/source/contributing/Quanta.pdf similarity index 100% rename from docs/source/developer-guidelines/Quanta.pdf rename to docs/source/contributing/Quanta.pdf diff --git a/docs/source/developer-guidelines/acceptance-tests.md b/docs/source/contributing/acceptance-tests.md similarity index 100% rename from docs/source/developer-guidelines/acceptance-tests.md rename to docs/source/contributing/acceptance-tests.md diff --git a/docs/source/developer-guidelines/accessibility-guidelines.md b/docs/source/contributing/accessibility-guidelines.md similarity index 100% rename from docs/source/developer-guidelines/accessibility-guidelines.md rename to docs/source/contributing/accessibility-guidelines.md diff --git a/docs/source/contributing/branch-policy.md b/docs/source/contributing/branch-policy.md new file mode 100644 index 0000000000..d274e78e38 --- /dev/null +++ b/docs/source/contributing/branch-policy.md @@ -0,0 +1,49 @@ +The Volto team enforces the following branch policy when developers contribute to its core. + +Releases of general packages (`@plone/generator-volto`, `@plone/scripts`, and so on) are cut from the `master` branch. + +stable and latest +: The terms _stable_ and _latest_ mean the same thing in this policy. + They refer to the stable and latest released version of Volto. + They have no branch names in git. + +canary +: The term _canary_ refers to the metaphorical canary in a coalmine; if an issue is detected following its release, the damage is limited to only those users who have installed it. + It usually includes experimental and breaking features for testing. + During the development process, a canary release will be cut from the `master` branch. + When it becomes worthy of a beta or release candidate version, a new numbered branch should be cut, and non-breaking changes must be merged into it. + +legacy +: A version that it is unsupported and receives no bug fixes. + It has no branch name in git. + +`master` +: This is the bleeding edge branch in git. + It is the branch upon which future development occurs, and from which future releases shall be cut. + + When we cut a release candidate, we: + + 1. create a new numbered git branch from master, and + 2. cut a release candidate version whose name aligns with the new numbered git branch. + + For example, when we cut the release candidate version 16.0.0-rc.1, we created a git branch `16.x.x`. + We also freeze the release candidate, and stop adding features to it. + This allows us to continue development on `master`, which may include both breaking changes that must not be backported, and bug fixes and feature additions that may be backported but only after the release candidate becomes final. + + When opening a pull request, the contributor must open it against `master`. + If the pull request is a feature or a bugfix, and if the release manager deems it useful to the latest version's branch, they may ask the contributor to backport it to that branch. + +`16.x.x` +: This is the current actively developed branch in git, meaning that it may receive new features and bug fixes. + Its version is currently at 16.0.0-rc.1 as a release candidate. + It will become the stable version upon the final release of version 16.0.0. + +`15.x.x` +: At the moment of this writing, `15.x.x` is the current stable branch in git. + Upon the final release of version 16.0.0, the `15.x.x` branch line will become legacy. + +## Translation contributing policy + +Due to the nature of `master` and `16.x.x` branches, some developments that may land in `master` may not be backported to `16.x.x`. This means that many translations that may come with those developments will be useless in the `16.x.x` branch and thus porting them to `16.x.x` makes no sense. + +So when contributing translations, please create PRs directly from branches created from `16.x.x` and point your PRs to that exact branch instead of `master`. diff --git a/docs/source/developer-guidelines/design-principles.md b/docs/source/contributing/design-principles.md similarity index 100% rename from docs/source/developer-guidelines/design-principles.md rename to docs/source/contributing/design-principles.md diff --git a/docs/source/developer-guidelines/icons.md b/docs/source/contributing/icons.md similarity index 100% rename from docs/source/developer-guidelines/icons.md rename to docs/source/contributing/icons.md diff --git a/docs/source/developer-guidelines/contributing.md b/docs/source/contributing/index.md similarity index 65% rename from docs/source/developer-guidelines/contributing.md rename to docs/source/contributing/index.md index b2b7a445b6..adc5e4d2aa 100644 --- a/docs/source/developer-guidelines/contributing.md +++ b/docs/source/contributing/index.md @@ -1,10 +1,10 @@ --- myst: html_meta: - "description": "A guide on how to contribute to Volto, the frontend for Plone." - "property=og:description": "A guide on how to contribute to Volto, the frontend for Plone." - "property=og:title": "Contributing to Volto" - "keywords": "Volto, Plone, frontend, React, guidelines" + "description": "How to contribute to Volto, the frontend for Plone." + "property=og:description": "How to contribute to Volto, the frontend for Plone." + "property=og:title": "How to contribute to Volto, the frontend for Plone." + "keywords": "Plone, Volto, contributing, developer, guidelines" --- (contributing-to-volto-label)= @@ -33,11 +33,11 @@ In your report, please specify a few things: - Include relevant screenshots, error messages, and stack traces. -(contributing-sign-and-return-the-plone-contributor-agreement-label)= +(contributing-volto-sign-and-return-the-plone-contributor-agreement-label)= ## Sign and return the Plone Contributor Agreement -The Volto Team reviews pull requests only from people with a GitHub account who have signed and returned the {ref}`Plone Contributor Agreement `, and subsequently been assigned to a Plone Team in GitHub. +The Volto Team reviews pull requests only from people with a GitHub account who have signed and returned the {ref}`Plone Contributor Agreement `, and subsequently been assigned to a Plone Team in GitHub. (contributing-branch-policy-label)= @@ -89,6 +89,38 @@ Specifically: - {doc}`./acceptance-tests` +(contributing-developer-guidelines-label)= + +## Developer guidelines + +Development and configuration of Volto is managed through your {ref}`choice of Plone installation method `. +You may choose to install Plone via {ref}`containers ` or from its {ref}`packages `. + +```{todo} +When referring to installation and configuration of Plone's backend, this part of the Volto documentation may have obsolete content. +The most current information for installing and configuring Plone is in {ref}`install-index-label`. +Please report any issues in the [Volto issue tracker](https://github.com/plone/volto/issues/). +``` + +```{toctree} +:maxdepth: 1 + +design-principles +style-guide +language-features +linting +react +redux +routing +icons +testing +acceptance-tests +accessibility-guidelines +typescript +volto-core-addons +``` + + (contributing-final-advice-label)= ## Final advice diff --git a/docs/source/developer-guidelines/language-features.md b/docs/source/contributing/language-features.md similarity index 100% rename from docs/source/developer-guidelines/language-features.md rename to docs/source/contributing/language-features.md diff --git a/docs/source/developer-guidelines/linting.md b/docs/source/contributing/linting.md similarity index 100% rename from docs/source/developer-guidelines/linting.md rename to docs/source/contributing/linting.md diff --git a/docs/source/developer-guidelines/react.md b/docs/source/contributing/react.md similarity index 100% rename from docs/source/developer-guidelines/react.md rename to docs/source/contributing/react.md diff --git a/docs/source/developer-guidelines/redux.md b/docs/source/contributing/redux.md similarity index 100% rename from docs/source/developer-guidelines/redux.md rename to docs/source/contributing/redux.md diff --git a/docs/source/developer-guidelines/routing.md b/docs/source/contributing/routing.md similarity index 100% rename from docs/source/developer-guidelines/routing.md rename to docs/source/contributing/routing.md diff --git a/docs/source/developer-guidelines/style-guide.md b/docs/source/contributing/style-guide.md similarity index 100% rename from docs/source/developer-guidelines/style-guide.md rename to docs/source/contributing/style-guide.md diff --git a/docs/source/developer-guidelines/testing.md b/docs/source/contributing/testing.md similarity index 100% rename from docs/source/developer-guidelines/testing.md rename to docs/source/contributing/testing.md diff --git a/docs/source/developer-guidelines/typescript.md b/docs/source/contributing/typescript.md similarity index 100% rename from docs/source/developer-guidelines/typescript.md rename to docs/source/contributing/typescript.md diff --git a/docs/source/developer-guidelines/volto-core-addons.md b/docs/source/contributing/volto-core-addons.md similarity index 100% rename from docs/source/developer-guidelines/volto-core-addons.md rename to docs/source/contributing/volto-core-addons.md diff --git a/docs/source/developer-guidelines/index.md b/docs/source/developer-guidelines/index.md deleted file mode 100644 index a96f92b02b..0000000000 --- a/docs/source/developer-guidelines/index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -myst: - html_meta: - "description": "Developer Guidelines" - "property=og:description": "Developer Guidelines" - "property=og:title": "Developer Guidelines" - "keywords": "Developer, Guidelines" ---- - -# Developer guidelines - -Development and configuration of Volto is managed through your {ref}`choice of Plone installation method `. -You may choose to install Plone via {ref}`containers ` or from its {ref}`packages `. - -```{todo} -When referring to installation and configuration of Plone's backend, this part of the Volto documentation may have obsolete content. -The most current information for installing and configuring Plone is in {ref}`install-index-label`. -Please report any issues in the [Volto issue tracker](https://github.com/plone/volto/issues/). -``` - -```{toctree} -:maxdepth: 1 - -contributing -design-principles -style-guide -language-features -linting -react -redux -routing -icons -testing -acceptance-tests -accessibility-guidelines -typescript -volto-core-addons -``` diff --git a/docs/source/index.md b/docs/source/index.md index 222455dae2..ee7723015f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -47,7 +47,7 @@ addons/index backend/index deploying/index upgrade-guide/index -developer-guidelines/index user-manual/index +contributing/index release-notes/index ``` diff --git a/news/4666.documentation b/news/4666.documentation new file mode 100644 index 0000000000..0ad620aa45 --- /dev/null +++ b/news/4666.documentation @@ -0,0 +1 @@ +Rename "Developer Guidelines" to "Contributing". @stevepiercy