search

plone / volto

React-based frontend for the Plone Content Management System
https://demo.plone.org/
MIT License
448 stars 610 forks source link

Too many installation docs (and other suggested improvements) #3289

Closed stevepiercy closed 9 months ago

stevepiercy commented 2 years ago

We have too many Volto installation docs.

I would strongly advocate for one, and only one, way to install Volto for development in Plone 6.

This would make it easier to maintain installation documentation and reduce frustration of developers.

As a couple of side notes:

  1. I would require, not make it optional, to use nvm. Alternatively, we should make a statement such as, "The Volto development team uses nvm for installing and managing versions of Node.js. We do not support any other node version manager or the lack of one. If you do not use nvm, then we assume you know what you are doing and can resolve issues on your own."
  2. Provide clear paths to install Volto using either Docker or a manual installation. The current docs are not structured clearly because all headings are at the same level and not in order. The proposed version aims to provide that structure and order.
  3. State "For simplicity in documentation, we use bash for a shell. Adjust commands according to your preferred shell flavor."
  4. Specify what characters are valid in a project name for npm init yo @plone/volto. Letters, number, dashes, underscores, other characters?
  5. Use "Install", not "Getting Started", buried under "Introduction". Elevate it.
  6. Separate "Installation" from "Development" documentation. Volto (and any other core Plone package) should still have its specific documentation for development purposes, such as for running tests.
tiberiuichim commented 2 years ago

Thank you @stevepiercy for working on this (and all your other work on documentation)!

ksuess commented 2 years ago

I updated Mastering Plone Development Training two weeks before by referencing Plone 6 documentation instructions and removing any self cooked instructions. So this is at least for the frontend part OK now. Glad that you picked up the idea to clean up the creative variety of installation instructions!

stevepiercy commented 2 years ago

Thanks @ksuess. I've added https://training.plone.org/5/mastering-plone/installation.html#installing-plone-frontend to the list above.

ksuess commented 2 years ago

Thanks @ksuess. I've added https://training.plone.org/5/mastering-plone/installation.html#installing-plone-frontend to the list above.

Just recently added both pages of Mastering Plone Development.

BTW this '/5/' in the uri is confusing…

stevepiercy commented 2 years ago

BTW this '/5/' in the uri is confusing…

See https://github.com/plone/training/issues/581

ksuess commented 2 years ago

BTW this '/5/' in the uri is confusing…

See plone/training#581

Oh my, another task…

stevepiercy commented 1 year ago

I've created a project to track all Install-related issues, Install Docs.

rileydog commented 1 year ago

@stevepiercy Hi, when i click on Install Docs, it goes to https://github.com/orgs/plone/projects/16 and gives a 404 error

stevepiercy commented 1 year ago

@rileydog oops, I opened it up to @plone/developers. Are you a member of that team?

rileydog commented 1 year ago

@stevepiercy - no I'm not part of the team

stevepiercy commented 1 year ago

@rileydog have you signed the Plone Contributor Agreement?

rileydog commented 1 year ago

@stevepiercy I'm not part of the team so i didn't sign the agreement. Im not a contributor, i just found the link didn't work for me.

stevepiercy commented 1 year ago

@rileydog I am not an organization Owner, so I cannot make it public. I am OK with making it public, but an organization Owner would need to change its visibility, and I have no clue who that might be. @plone/plone-foundation-board any of you know? IMO all GitHub projects under the Organization should be publicly visible for transparency.

The best I can do is make the project available to members of the organization, which is @plone/developers, and have you sign the CA to become a member of that group. And of course ask someone else to change the visibility, which I have done here.

Finally, the project is merely a collection of issues across several repos in their issue trackers, so you can search for them that way.

aclark4life commented 1 year ago

I'm an organization owner … anyone know why it's not public, and/or if it's OK to make public?

ericof commented 1 year ago

As documentation and volto repositories require the contributor agreement before any contribution is made, I would keep the project restricted to those who signed the agreement.

On Mon, Jan 2, 2023, 19:35 Jeffrey A Clark (Alex) @.***> wrote:

I'm an organization owner … anyone know why it's not public, and/or if it's OK to make public?

— Reply to this email directly, view it on GitHub https://github.com/plone/volto/issues/3289#issuecomment-1369250446, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACKWXUNM4BSDJJ7ZL7JBA3WQNJZ3ANCNFSM5UYJBREA . You are receiving this because you are on a team that was mentioned.Message ID: @.***>

stevepiercy commented 1 year ago

Signing the CA is still enforced when a contributor submits a PR to any Plone repo, but that has nothing to do with being able to read an issue. In fact, by allowing issues to be readable by the public is how many people become contributors, including through GSoC.

Release Plone 6 docs is already public. This GitHub project is a subset of that and is merely a collection of issues that are publicly readable in their respective repos. What needs to be kept private that is already public in separate repos?

polyester commented 1 year ago

There is a difference between the whole organization (which has, and will always have, private repos for things like the admin&infra team and security team) and "projects", which can have per-project settings. As long as a project (which is just a collection of issues) has issues from public repos, the project visibility can be set to "public" as well. This does not change who can interact with it.

I've set the visibility of the "Install docs" and "Release Plone 6 docs" projects to "public"

stevepiercy commented 9 months ago

I'm going to close this issue, because we have resolved most of the issues and consolidated documentation into include files. Specific issues remain, but they can be addressed separately.