From c6c2fb08886261e1531a654ad79d650c00f2d8d2 Mon Sep 17 00:00:00 2001 From: as-op Date: Thu, 29 Aug 2024 11:34:01 +0200 Subject: [PATCH] remove manual redirect pages (will be handled by site builder); sort dev setup docs; remove repeated content --- docs/README.md | 2 +- docs/development/README.md | 5 +-- docs/development/concepts/README.md | 22 ++++++------ .../application-architecture/README.md | 8 ----- .../create-openproject-plugin/README.md | 2 +- .../development-environment/README.md | 34 +++++++++++++++++++ .../docker-macos}/README.md | 3 +- .../docker}/README.md | 3 +- .../linux}/README.md | 24 +------------ .../macos}/README.md | 24 +------------ docs/development/environments/README.md | 10 ------ docs/development/localhost-ssl/README.md | 9 +---- .../product-development-handbook/README.md | 2 +- docs/development/releases/README.md | 3 -- docs/development/running-tests/README.md | 6 ++-- .../installation/manual/README.md | 5 --- 16 files changed, 59 insertions(+), 103 deletions(-) delete mode 100644 docs/development/concepts/application-architecture/README.md create mode 100644 docs/development/development-environment/README.md rename docs/development/{development-environment-docker-macos => development-environment/docker-macos}/README.md (96%) rename docs/development/{development-environment-docker => development-environment/docker}/README.md (99%) rename docs/development/{development-environment-ubuntu => development-environment/linux}/README.md (90%) rename docs/development/{development-environment-osx => development-environment/macos}/README.md (90%) delete mode 100644 docs/development/environments/README.md delete mode 100644 docs/development/releases/README.md diff --git a/docs/README.md b/docs/README.md index 84d3456a947b..e7dff7774c12 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,7 +39,7 @@ Please see our [Use Cases section](./use-cases/) for detailed how-to guides and ## Development -* [Full development environment for developers on Ubuntu](./development/development-environment-ubuntu) and [Mac OS X](./development/development-environment-osx) +* [Full development environment for developers](./development/development-environment) * [Developing plugins](./development/create-openproject-plugin) * [Developing OmniAuth Plugins](./development/create-omniauth-plugin) * [Running tests](./development/running-tests) diff --git a/docs/development/README.md b/docs/development/README.md index aee88f742be9..5b091adb4e83 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -96,10 +96,7 @@ If you want to contribute to OpenProject, please make sure to accept our Contrib ## Additional resources -* [Development environment for Ubuntu 18.04](development-environment-ubuntu) -* [Development environment for Mac OS X](development-environment-osx) -* [Development environment using docker](development-environment-docker) - +* [Development environment](development-environment) * [Developing Plugins](create-openproject-plugin) * [Running Tests](running-tests) * [API Documentation](../api) diff --git a/docs/development/concepts/README.md b/docs/development/concepts/README.md index e41d5fc66eda..784312f9d056 100644 --- a/docs/development/concepts/README.md +++ b/docs/development/concepts/README.md @@ -12,14 +12,14 @@ This guide will introduce some concepts and give you a big picture of the develo Please choose an area that you would like to read about: -| Topic | Content | -|------------------------------------------------------|:------------------------------------------------------------------------------| -| [Application architecture](application-architecture) | An introduction of the application architecture used at OpenProject. | -| [State management](state-management) | How does the frontend handle state and react to changes? | -| [HAL resources](hal-resources) | What are HAL resources and how are they used in the frontend? | -| [Permissions](permissions) | How are roles and permissions handled in OpenProject code? | -| [Translations](translations) | How are translations used and built? | -| [Resource schemas](resource-schemas) | What is a schema and how is it tied to an editable resource? | -| [Resource changesets](resource-changesets) | How is change tracked to resources in the frontend? How to save the changes. | -| [Inline editing](inline-editing) | How does inline editing and the edit field functionality work in OpenProject? | -| [Queries and QuerySpace](queries) | What is the Query API concept and how is it used in the frontend? | +| Topic | Content | +|---------------------------------------------------------|:------------------------------------------------------------------------------| +| [Application architecture](../application-architecture) | An introduction of the application architecture used at OpenProject. | +| [State management](state-management) | How does the frontend handle state and react to changes? | +| [HAL resources](hal-resources) | What are HAL resources and how are they used in the frontend? | +| [Permissions](permissions) | How are roles and permissions handled in OpenProject code? | +| [Translations](translations) | How are translations used and built? | +| [Resource schemas](resource-schemas) | What is a schema and how is it tied to an editable resource? | +| [Resource changesets](resource-changesets) | How is change tracked to resources in the frontend? How to save the changes. | +| [Inline editing](inline-editing) | How does inline editing and the edit field functionality work in OpenProject? | +| [Queries and QuerySpace](queries) | What is the Query API concept and how is it used in the frontend? | diff --git a/docs/development/concepts/application-architecture/README.md b/docs/development/concepts/application-architecture/README.md deleted file mode 100644 index 0e48122469fa..000000000000 --- a/docs/development/concepts/application-architecture/README.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_navigation: - title: Application architecture ---- - -# Application architecture - -This guide has been integrated into the [application architecture documentation](../../application-architecture/). diff --git a/docs/development/create-openproject-plugin/README.md b/docs/development/create-openproject-plugin/README.md index 4300f774b669..6f43cb25a369 100644 --- a/docs/development/create-openproject-plugin/README.md +++ b/docs/development/create-openproject-plugin/README.md @@ -136,7 +136,7 @@ It is probably best to use READMEs of already released plugins as a template. Activity, Issue Tracking, Time Tracking, Forums, and Backlogs are default. Also, the My Project Page should only show Project Description and Tickets blocks. 3. Create a news article about the newly released plugin and its features. -4. Twitter with a link to the news article. +4. Share a link to the news article on social media. 5. If the plugin is referenced in our feature tour, add a download link to the plugin in the feature tour ## Frontend plugins [WIP] diff --git a/docs/development/development-environment/README.md b/docs/development/development-environment/README.md new file mode 100644 index 000000000000..58ecee41d708 --- /dev/null +++ b/docs/development/development-environment/README.md @@ -0,0 +1,34 @@ +--- +sidebar_navigation: + title: Development setup +description: OpenProject development setup +keywords: development setup +--- + +# OpenProject development setup + +| OS/Method | Description | +|------------------------------------|-----------------------------------------------------------------------------------| +| [Ubuntu / Debian](linux) | Develop setup on Linux | +| [via docker](docker) | The quickest way to get started developing OpenProject is to use the docker setup | +| [via docker (MacOS)](docker-macos) | MacOS specific docker topics | +| [MacOS](macos) | Develop setup on MacOS | + + +### Start Coding + +Please have a look at [our development guidelines](../code-review-guidelines/) for tips and guides on how to start +coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible. +Also, take a look at the `doc` directory in our sources, especially +the [how to run tests](../running-tests) documentation (we like to have automated tests for every new developed feature). + +### Troubleshooting + +The OpenProject logfile can be found in `log/development.log`. + +If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process). + +### Questions, Comments, and Feedback + +If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the +appropriate [forum](https://community.openproject.org/projects/openproject/boards/9). diff --git a/docs/development/development-environment-docker-macos/README.md b/docs/development/development-environment/docker-macos/README.md similarity index 96% rename from docs/development/development-environment-docker-macos/README.md rename to docs/development/development-environment/docker-macos/README.md index 4457931890fc..7ff3c7c3bb1f 100644 --- a/docs/development/development-environment-docker-macos/README.md +++ b/docs/development/development-environment/docker-macos/README.md @@ -1,13 +1,14 @@ --- sidebar_navigation: title: Development setup via docker on MacOS + short_title: Setup via Docker on MacOS description: OpenProject development setup via docker on MacOS keywords: development setup docker macos --- # OpenProject development setup via docker (MacOS) -This guide covers observed nuances with the docker runtime on MacOS. Please ensure you've gone through the general [OpenProject development setup via docker](../development-environment-docker) guide before proceeding. +This guide covers observed nuances with the docker runtime on MacOS. Please ensure you've gone through the general [OpenProject development setup via docker](../docker) guide before proceeding. ## Docker on MacOS File System Performance diff --git a/docs/development/development-environment-docker/README.md b/docs/development/development-environment/docker/README.md similarity index 99% rename from docs/development/development-environment-docker/README.md rename to docs/development/development-environment/docker/README.md index d74283ec7735..a0131770acfc 100644 --- a/docs/development/development-environment-docker/README.md +++ b/docs/development/development-environment/docker/README.md @@ -1,6 +1,7 @@ --- sidebar_navigation: title: Development setup via docker + short_title: Setup via Docker description: OpenProject development setup via docker keywords: development setup docker --- @@ -464,7 +465,7 @@ Once the keycloak service is started and running, you can access the keycloak in and login with initial username and password as `admin`. Keycloak being an OpenID connect provider, we need to setup an OIDC integration for OpenProject. -[Setup OIDC (keycloak) integration for OpenProject](../../installation-and-operations/misc/custom-openid-connect-providers/#keycloak) +[Setup OIDC (keycloak) integration for OpenProject](../../../installation-and-operations/misc/custom-openid-connect-providers/#keycloak) Once the above setup is completed, In the root `docker-compose.override.yml` file, uncomment all the environment in `backend` service for keycloak and set the values according to configuration done in keycloak for OpenProject Integration. diff --git a/docs/development/development-environment-ubuntu/README.md b/docs/development/development-environment/linux/README.md similarity index 90% rename from docs/development/development-environment-ubuntu/README.md rename to docs/development/development-environment/linux/README.md index 995a021b55a1..94e719700759 100644 --- a/docs/development/development-environment-ubuntu/README.md +++ b/docs/development/development-environment/linux/README.md @@ -1,6 +1,7 @@ --- sidebar_navigation: title: Development setup on Debian / Ubuntu + short_title: Setup on Debian / Ubuntu description: OpenProject development setup on Debian / Ubuntu keywords: development setup debian ubuntu linux --- @@ -18,8 +19,6 @@ shall NOT be present before. **Please note**: This guide is NOT suitable for a production setup, but only for developing with it! -Remark: *At the time of writing* in this page refers to 12/10/2021 - If you find any bugs or you have any recommendations for improving this tutorial, please, feel free to send a pull request or comment in the [OpenProject forums](https://community.openproject.org/projects/openproject/boards). @@ -350,24 +349,3 @@ in a production setting.** ```shell RAILS_ENV=development bin/rails runner "Delayed::Job.delete_all" ``` - -### Start Coding - -Please have a look at [our development guidelines](../code-review-guidelines/) for tips and guides on how to start -coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible. -Also, take a look at the `doc` directory in our sources, especially -the [how to run tests](https://github.com/opf/openproject/tree/dev/docs/development/running-tests) documentation (we -like to have automated tests for every new developed feature). - -### Troubleshooting - -The OpenProject logfile can be found in `log/development.log`. - -If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process). - -### Questions, Comments, and Feedback - -If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the -appropriate community.openproject.org [forum](https://community.openproject.org/projects/openproject/boards/9). -[Follow OpenProject on twitter](https://twitter.com/openproject), and -follow [the news](https://www.openproject.org/blog) to stay up to date. diff --git a/docs/development/development-environment-osx/README.md b/docs/development/development-environment/macos/README.md similarity index 90% rename from docs/development/development-environment-osx/README.md rename to docs/development/development-environment/macos/README.md index 1ba17bd97e1c..5d1ed3b0e16c 100644 --- a/docs/development/development-environment-osx/README.md +++ b/docs/development/development-environment/macos/README.md @@ -1,6 +1,7 @@ --- sidebar_navigation: title: Development setup on MacOS + short_title: Setup on MacOS description: OpenProject development setup on Mac OS keywords: development setup macos --- @@ -207,8 +208,6 @@ Now, run the following tasks to migrate and seed the dev database, and prepare t RAILS_ENV=development bin/rails db:seed ``` -1 - ### Run OpenProject through overmind You can run all required workers of OpenProject through `overmind`, which combines them in a single tab. Optionally, you @@ -334,24 +333,3 @@ in a production setting.** ```shell RAILS_ENV=development bin/rails runner "Delayed::Job.delete_all" ``` - -### Start Coding - -Please have a look at [our development guidelines](../code-review-guidelines) for tips and guides on how to start -coding. We have advice on how to get your changes back into the OpenProject core as smooth as possible. -Also, take a look at the `doc` directory in our sources, especially -the [how to run tests](https://github.com/opf/openproject/blob/dev/docs/development/running-tests) documentation (we -like to have automated tests for every new developed feature). - -### Troubleshooting - -The OpenProject logfile can be found in `log/development.log`. - -If an error occurs, it should be logged there (as well as in the output to STDOUT/STDERR of the rails server process). - -### Questions, Comments, and Feedback - -If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the -appropriate community.openproject.org [forum](https://community.openproject.org/projects/openproject/boards/9). -[Follow OpenProject on twitter](https://twitter.com/openproject), and -follow [the news](https://www.openproject.org/blog) to stay up to date. diff --git a/docs/development/environments/README.md b/docs/development/environments/README.md deleted file mode 100644 index 11b7bdeaffa7..000000000000 --- a/docs/development/environments/README.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -sidebar_navigation: - title: Environments -description: Get an overview of the different environments at play in the development phases of OpenProject -keywords: environments, CI, development ---- - -# Environments - -This guide has been integrated into the [application architecture documentation](../application-architecture/). diff --git a/docs/development/localhost-ssl/README.md b/docs/development/localhost-ssl/README.md index 3af70041e542..58e95f916909 100644 --- a/docs/development/localhost-ssl/README.md +++ b/docs/development/localhost-ssl/README.md @@ -93,7 +93,7 @@ application server. You can do that with `/usr/sbin/setsebool -P httpd_can_netwo ## Step 4: Configure OpenProject for HTTPS usage We assume you have already configured your OpenProject local development environment -as [described in this guide](../development-environment-ubuntu). You will need to add your custom host name +as [described in this guide](../development-environment). You will need to add your custom host name to the environment. You can use this variable to do so. ```yaml @@ -133,10 +133,3 @@ setup a reverse proxy in docker, like [traefik](https://traefik.io/). Then follo > **Reminder**: This setup is still experimental and under further development. Use it only, when you know what you are doing. - -## Questions, Comments, and Feedback - -If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the -appropriate community.openproject.org [forum](https://community.openproject.org/projects/openproject/boards/9). -[Follow OpenProject on twitter](https://twitter.com/openproject), and -follow [the news](https://www.openproject.org/blog) to stay up to date. diff --git a/docs/development/product-development-handbook/README.md b/docs/development/product-development-handbook/README.md index e6c60f96e640..eb3690209e85 100644 --- a/docs/development/product-development-handbook/README.md +++ b/docs/development/product-development-handbook/README.md @@ -343,7 +343,7 @@ The entire team documents possible improvements for the next release. ### 4.1 Version/Release -A version is the name given to a collection of features and/or bugfixes. A release is the publicly available version of the OpenProject software. More information is provided on the [release page](../releases/). +A version is the name given to a collection of features and/or bugfixes. A release is the publicly available version of the OpenProject software. More information is provided on the [Application architecture page](../application-architecture/#patch-and-change-management). ### 4.2 RICE Score diff --git a/docs/development/releases/README.md b/docs/development/releases/README.md deleted file mode 100644 index d21561c7da86..000000000000 --- a/docs/development/releases/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Releases - -This page has been integrated into the [application architecture guide](../application-architecture/#patch-and-change-management). diff --git a/docs/development/running-tests/README.md b/docs/development/running-tests/README.md index 3f482e5797eb..d833d8886f4d 100644 --- a/docs/development/running-tests/README.md +++ b/docs/development/running-tests/README.md @@ -119,7 +119,7 @@ Smoke tests are automated and manual tests to ensure the main application featur **Best practices** - Automate smoke testing on top of manual testing when possible -- Run after deployments to the appropriate [environments](../environments), e.g., the edge environment for features of the next release and staging environment for bug fixes to a stable release +- Run after deployments to the appropriate [environments](../application-architecture/#environments), e.g., the edge environment for features of the next release and staging environment for bug fixes to a stable release - Keep smoke tests updated so that they can evolve together with the application **References** @@ -251,7 +251,7 @@ Upgrade tests are manually performed for major code changes and data migrations #### Usability testing -When new features or changes to the application are available on our [Edge or Community environments](../environments), product team members, customers, and community users can provide usability feedback on how the change is perceived. +When new features or changes to the application are available on our [Edge or Community environments](../application-architecture/#environments), product team members, customers, and community users can provide usability feedback on how the change is perceived. **Key objectives and effects** @@ -725,7 +725,7 @@ good as a test server. ### Running tests locally in Docker Most of the above applies to running tests locally, with some docker specific setup changes that are discussed [in the -docker development documentation](../development-environment-docker). +docker development documentation](../development-environment/docker). ### Generators diff --git a/docs/installation-and-operations/installation/manual/README.md b/docs/installation-and-operations/installation/manual/README.md index 1664c77b412f..ca8887e63dff 100644 --- a/docs/installation-and-operations/installation/manual/README.md +++ b/docs/installation-and-operations/installation/manual/README.md @@ -456,8 +456,3 @@ If you need to restart the server (for example after a configuration change), do With each new OpenProject core version, the plug-ins might need to be updated. Please make sure that the plug-in versions of all you plug-ins works with the OpenProject version you use. Many plug-ins follow the OpenProject version with their version number (So, if you have installed OpenProject version 4.1.0, the plug-in should also have the version 4.1.0). - -## Questions, comments, and feedback - -If you have any further questions, comments, feedback, or an idea to enhance this guide, please tell us at the appropriate community [forum](https://community.openproject.org/projects/openproject/boards/9). -[Follow OpenProject on twitter](https://twitter.com/openproject), and follow the news on [openproject.org](https://www.openproject.org) to stay up to date.