|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Contributions are welcome! |
| 4 | + |
| 5 | +## Quick Start 🏁 |
| 6 | + |
| 7 | +### Prerequisites ✅ |
| 8 | + |
| 9 | +- An [operating system](https://6.docs.plone.org/install/create-project-cookieplone.html#prerequisites-for-installation) that runs all the requirements mentioned. |
| 10 | +- [uv](https://6.docs.plone.org/install/create-project-cookieplone.html#uv) |
| 11 | +- [nvm](https://6.docs.plone.org/install/create-project-cookieplone.html#nvm) |
| 12 | +- [Node.js and pnpm](https://6.docs.plone.org/install/create-project.html#node-js) 24 |
| 13 | +- [Make](https://6.docs.plone.org/install/create-project-cookieplone.html#make) |
| 14 | +- [Git](https://6.docs.plone.org/install/create-project-cookieplone.html#git) |
| 15 | +- [Docker](https://docs.docker.com/get-started/get-docker/) (optional) |
| 16 | + |
| 17 | +### Installation 🔧 |
| 18 | + |
| 19 | +1. Clone this repository, then change your working directory. |
| 20 | + |
| 21 | + ```shell |
| 22 | + git clone git@github.com:kitconcept/kitconcept-keywordmanager.git |
| 23 | + cd kitconcept-keywordmanager |
| 24 | + ``` |
| 25 | + |
| 26 | +2. Install this code base. |
| 27 | + |
| 28 | + ```shell |
| 29 | + make install |
| 30 | + ``` |
| 31 | + |
| 32 | +### Fire Up the Servers 🔥 |
| 33 | + |
| 34 | +1. Create a new Plone site on your first run. |
| 35 | + |
| 36 | + ```shell |
| 37 | + make backend-create-site |
| 38 | + ``` |
| 39 | + |
| 40 | +2. Start the backend at http://localhost:8080/. |
| 41 | + |
| 42 | + ```shell |
| 43 | + make backend-start |
| 44 | + ``` |
| 45 | + |
| 46 | +3. In a new shell session, start the frontend at http://localhost:3000/. |
| 47 | + |
| 48 | + ```shell |
| 49 | + make frontend-start |
| 50 | + ``` |
| 51 | + |
| 52 | +Voila! Your Plone site should be live and kicking! 🎉 |
| 53 | + |
| 54 | +### Local Stack Deployment 📦 |
| 55 | + |
| 56 | +Deploy a local Docker Compose environment that includes the following. |
| 57 | + |
| 58 | +- Docker images for Backend and Frontend 🖼️ |
| 59 | +- A stack with a Traefik router and a PostgreSQL database 🗃️ |
| 60 | +- Accessible at [http://kitconcept-keywordmanager.localhost](http://kitconcept-keywordmanager.localhost) 🌐 |
| 61 | + |
| 62 | +Run the following commands in a shell session. |
| 63 | + |
| 64 | +```shell |
| 65 | +make stack-create-site |
| 66 | +make stack-start |
| 67 | +``` |
| 68 | + |
| 69 | +And... you're all set! Your Plone site is up and running locally! 🚀 |
| 70 | +
|
| 71 | +## Project structure 🏗️ |
| 72 | +
|
| 73 | +This monorepo consists of the following distinct sections: |
| 74 | +
|
| 75 | +- **backend**: Houses the API and Plone installation, utilizing pip instead of buildout, and includes a policy package named kitconcept.keywordmanager. |
| 76 | +- **frontend**: Contains the React (Volto) package. |
| 77 | +- **devops**: Encompasses Docker stack, Ansible playbooks, and cache settings. |
| 78 | +- **docs**: Scaffold for writing documentation for your project. |
| 79 | +
|
| 80 | +### Why this structure? 🤔 |
| 81 | +
|
| 82 | +- All necessary codebases to run the site are contained within the repository (excluding existing add-ons for Plone and React). |
| 83 | +- Specific GitHub Workflows are triggered based on changes in each codebase (refer to .github/workflows). |
| 84 | +- Simplifies the creation of Docker images for each codebase. |
| 85 | +- Demonstrates Plone installation/setup without buildout. |
| 86 | +
|
| 87 | +## Code quality assurance 🧐 |
| 88 | +
|
| 89 | +To check your code against quality standards, run the following shell command. |
| 90 | +
|
| 91 | +```shell |
| 92 | +make check |
| 93 | +``` |
| 94 | +
|
| 95 | +### Format the codebase |
| 96 | +
|
| 97 | +To format and rewrite the code base, ensuring it adheres to quality standards, run the following shell command. |
| 98 | +
|
| 99 | +```shell |
| 100 | +make format |
| 101 | +``` |
| 102 | +
|
| 103 | +| Section | Tool | Description | Configuration | |
| 104 | +| -------- | --------- | --------------------------------------- | ---------------------------------------------------- | |
| 105 | +| backend | Ruff | Python code formatting, imports sorting | [`backend/pyproject.toml`](./backend/pyproject.toml) | |
| 106 | +| backend | `zpretty` | XML and ZCML formatting | -- | |
| 107 | +| frontend | ESLint | Fixes most common frontend issues | [`frontend/.eslintrc.js`](.frontend/.eslintrc.js) | |
| 108 | +| frontend | prettier | Format JS and Typescript code | [`frontend/.prettierrc`](.frontend/.prettierrc) | |
| 109 | +| frontend | Stylelint | Format Styles (css, less, sass) | [`frontend/.stylelintrc`](.frontend/.stylelintrc) | |
| 110 | +
|
| 111 | +Formatters can also be run within the `backend` or `frontend` folders. |
| 112 | +
|
| 113 | +### Linting the codebase |
| 114 | +
|
| 115 | +or `lint`: |
| 116 | +
|
| 117 | +```shell |
| 118 | +make lint |
| 119 | +``` |
| 120 | +
|
| 121 | +| Section | Tool | Description | Configuration | |
| 122 | +| -------- | --------------------- | ----------------------------------------- | ---------------------------------------------------- | |
| 123 | +| backend | Ruff | Checks code formatting, imports sorting | [`backend/pyproject.toml`](./backend/pyproject.toml) | |
| 124 | +| backend | Pyroma | Checks Python package metadata | -- | |
| 125 | +| backend | check-python-versions | Checks Python version information | -- | |
| 126 | +| backend | `zpretty` | Checks XML and ZCML formatting | -- | |
| 127 | +| frontend | ESLint | Checks JS / Typescript lint | [`frontend/.eslintrc.js`](.frontend/.eslintrc.js) | |
| 128 | +| frontend | prettier | Check JS / Typescript formatting | [`frontend/.prettierrc`](.frontend/.prettierrc) | |
| 129 | +| frontend | Stylelint | Check Styles (css, less, sass) formatting | [`frontend/.stylelintrc`](.frontend/.stylelintrc) | |
| 130 | +
|
| 131 | +Linters can be run individually within the `backend` or `frontend` folders. |
| 132 | +
|
| 133 | +## Internationalization 🌐 |
| 134 | +
|
| 135 | +Generate translation files for Plone and Volto with ease: |
| 136 | +
|
| 137 | +```shell |
| 138 | +make i18n |
| 139 | +``` |
| 140 | +
|
| 141 | +## Credits and acknowledgements 🙏 |
| 142 | +
|
| 143 | +This add-on is based on code from Products.PloneKeywordManager, adapted and extended for Plone 6 & Volto. |
| 144 | +
|
| 145 | +### Origins of PloneKeywordManager |
| 146 | +
|
| 147 | +PloneKeywordManager was originally written by Maik Jablonski at the Plone Paderborn Sprint in September 2003, an event funded by the Bertelsmann Foundation. Alexander Limi of Plone Solutions contributed the initial user interface updates and setup code, and Joe Geldart of Netalley Networks later brought the templates up to the Plone 2.0 format. Maik Jablonski subsequently donated the code to the Collective, allowing the community to maintain and extend it going forward. |
| 148 | +
|
| 149 | +Since then, the package has been maintained and updated through successive Plone releases by numerous contributors within the Plone Collective. The full list of contributors is available on [GitHub](https://github.com/collective/Products.PloneKeywordManager/graphs/contributors/). |
| 150 | +
|
| 151 | +### This add-on |
| 152 | +
|
| 153 | +Building on that foundation, this package was created by the kitconcept GmbH to bring keyword management Volto. |
| 154 | +
|
| 155 | +### Long-term goal: bringing keyword management into Plone core |
| 156 | +
|
| 157 | +There is an ongoing effort to bring keyword-management functionality into Plone core itself, tracked as PLIP: Keyword Manager. This add-on is intended as a step toward that goal — a working, up-to-date implementation that can inform (and hopefully eventually be folded into) that core integration. Getting there will require several steps: stabilizing the add-on for Plone 6, gathering community feedback, aligning with the Volto/core UI patterns, and going through the PLIP review process. Contributions and feedback toward that end are welcome. |
| 158 | +
|
| 159 | +Thanks to Maik Jablonski and everyone who has contributed to Products.PloneKeywordManager over the years for the original work this builds on. |
0 commit comments