Merge branch 'IBX-6404-bundle-extension' of github.com:ibexa/document…

…ation-developer into IBX-6404-bundle-extension
ibexa · Nov 15, 2023 · d8d531c · d8d531c
2 parents cfcadb0 + 87ea868
commit d8d531c
Show file tree

Hide file tree

Showing 10 changed files with 75 additions and 55 deletions.
diff --git a/docs/administration/img/bundle_github_structure.png b/docs/administration/img/bundle_github_structure.png
diff --git a/docs/administration/img/bundle_github_template.png b/docs/administration/img/bundle_github_template.png
diff --git a/docs/administration/img/bundle_page_block.png b/docs/administration/img/bundle_page_block.png
diff --git a/...ion/packages_and_bundles/create_bundle.md → ...ization/bundle_extension/create_bundle.md b/...ion/packages_and_bundles/create_bundle.md → ...ization/bundle_extension/create_bundle.md
@@ -1,13 +1,12 @@
 ---
-description: All code contributions to Ibexa DXP must follow package and bundle structure and namespace standards.
+description: Create a bundle extension for Ibexa DXP.
 ---
 
 # Create bundle
 
-The following section explains the whole process from creating a bundle from scratch to uploading it on the [packagist.org](https://packagist.org/) website.
-
-A bundle is modular structure that contain related functionality and can be integrated into an application.
-[Follow specific strucutre](package_structure.md/#package-and-bundle-structure-and-namespaces).
+A bundle is a reusable [[= product_name =]] extension that can be integrated.
+To ensure full compatibility, follow the structure specifications described in the 
+[package strucutre](package_structure.md/#package-and-bundle-structure-and-namespaces) section.
 
 The bundle extension described here is called `AcmeCurrencyExchangeRate` and enables a new page block which displays a currency exchange rate on your site.
 
@@ -70,20 +69,23 @@ php bin/ibexa-bundle-generator currency-exchange-rate currency-exchange-rate-di
 
 ## Use GitHub template
 
-https://github.com/ibexa/bundle-template
+1\. Go to the [[= product_name_base =]] [GitHub repository](https://github.com/ibexa/bundle-template).
+
+2\. In the upper-right corner, click the **Use this template** button, and select **Create a new repository**.
+
+3\. Provide repository name. Optionally, you can add description for the bundle.
+Next, click **Create repository**.
 
-Directory structure for AcmeCurrencyExchangeRate
-podac url
-button use template
-<!-- ekran gdzie podac parametry dla repozytorium -->
-<!-- [dodac strukture katalogu, screen albo diagram] -->
+![GitHub template](bundle_github_template.png)
 
 
 Once the repository is created, a workflow starts which generates a bundle structure.
-- Vendor namespace is generated from the orgnization name: github/github user name.
+
+Vendor namespace is generated from the orgnization name: github/github username.
 Package and bundle name inherits from repository name.
 
-<!-- screenshot z rezultatem -->
+![GitHub template](bundle_github_structure.png)
+
 
 ### Bundle directory structure
 
@@ -122,16 +124,14 @@ Generated bundle consists of the following structure:
 Where:
 
 
-- LICENSE - a license file, GPL v2 by default
-- README.md - a readme file with bundle description, its version and install instructions
+- `LICENSE` - a license file, GPL v2 by default
+- `README.md` - a readme file with bundle description, its version and install instructions
 - `composer.json` - a package definition
 - `deptrac.yaml` - a tool for static code analysis for PHP, checks the coherence of package architecture, for more information see [deptrac](https://qossmic.github.io/deptrac/) documentation.
 - `package.json` - frontend dependencies, for more information, see [about packages and modules](https://docs.npmjs.com/about-packages-and-modules).
 - `phpstan.neon` - phpstan configuration, a tool for static code analysis for PHP, scans, and evaluates codebase to find errors, and bugs, for more information, see the [documentation](https://phpstan.org/user-guide/getting-started).
 - `phpunit.xml.dist` - config for phpunit, unit and integration tests - see [documentation](https://phpunit.de/getting-started/phpunit-10.html).
 - src and tests follow the base catalog structure, according to [package structure](https://phpunit.de/getting-started/phpunit-10.html) docs.
-<!-- - `src/` - delivers a default configuration, how to extract translation from code, generate xlif files,
-          contains classes related to the bundle logic -->
 
 To fully use the possibilities of the bundle, get familiar with the structure:
 
@@ -191,7 +191,7 @@ For more information, see [bundles](../../../administration/project_organization
 
 !!! note
 
-  Make sure you follow naming convention to ensure clarity.
+    Make sure you follow naming convention to ensure clarity.
 
 In the `/src` create a ACMECurrencyExchangeRateBundle class:
 

diff --git a/...n/packages_and_bundles/install_package.md → ...ation/bundle_extension/install_package.md b/...n/packages_and_bundles/install_package.md → ...ation/bundle_extension/install_package.md
@@ -1,7 +1,9 @@
+---
+description: Install created bundle extension into Ibexa DXP.
+---
+
 # Install bundle
 
-
-
 ## Add repository to composer
 
 To be able to install the bundle to your [[= product_name_base =]] project, first, update the requirements.
@@ -33,6 +35,7 @@ Next, add the repository to the `composer.json`:
     }
 ```
 
+## Install bundle into application
 
 On your [[= product_name_base =]] root project run:
  
@@ -71,4 +74,7 @@ The newly installed bundle should be visible in the **Composer** tab in **Admin*
 
 ## Add currency exchange page block
 
+Go to Page Builder edit mode. The Currency exchange block should be visible and available in the **Elements** panel.
+
 
+![Currency exchange page block](bundle_page_block.png)
diff --git a/...packages_and_bundles/package_structure.md → ...ion/bundle_extension/package_structure.md b/...packages_and_bundles/package_structure.md → ...ion/bundle_extension/package_structure.md
diff --git a/docs/administration/project_organization/bundle_extension/upload_packagist.md b/docs/administration/project_organization/bundle_extension/upload_packagist.md
@@ -0,0 +1,42 @@
+---
+description: Upload created bundle extension to Packagist.
+---
+
+# Upload bundle to Packagist
+
+The following section explains how to upload created bundle  on the [packagist.org](https://packagist.org/) website.
+
+1\. Go to the Packagist website and click **Submit**.
+
+2\. Provide the repository URL to your package, for example, 
+`https://github.com/githubusername/example-3rd-party-extension`
+
+
+!!! note
+    When you add a new feature, you need to create a tag. 
+
+
+3\. In PHPStorm or other PHP IntelliJ editor, go to **Commits** -> **Log** and create a new tag.
+
+4\. Link your bundle repository with Packagist.
+Make sure the repository is set to public.
+Each time you add a new feature to your bundle, you need to also add a new tag.
+
+5\. Click the **Check** button to verify the bundle completeness.
+
+In `composer.json` in the `repositories` indicate the type and bundle URL:
+
+```json
+"repositories": {
+        "ibexa": {
+            "type": "composer",
+            "url": "https://updates.ibexa.co"
+        },
+        "acme/currency-exchange-rate":{
+            "type": "vcs",
+            "url": "https://github.com/githubusername/example-3rd-party-extension"
+        }
+    }
+```
+
+Any change in repository immediately affects the other bundle so you can see the changes.
diff --git a/docs/administration/project_organization/packages_and_bundles/upload_packagist.md b/docs/administration/project_organization/packages_and_bundles/upload_packagist.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -90,11 +90,11 @@ nav:
             - Project organization: administration/project_organization/project_organization.md
             - Architecture: administration/project_organization/architecture.md
             - Bundles: administration/project_organization/bundles.md
-            - Packages and bundles:
-                - Package structure: administration/project_organization/packages_and_bundles/package_structure.md
-                - Create bundle: administration/project_organization/packages_and_bundles/create_bundle.md
-                - Install bundle: administration/project_organization/packages_and_bundles/install_package.md
-                - Upload on Packagist: administration/project_organization/packages_and_bundles/upload_packagist.md
+            - Bundle extension:
+                - Package structure: administration/project_organization/bundle_extension/package_structure.md
+                - Create bundle: administration/project_organization/bundle_extension/create_bundle.md
+                - Install bundle: administration/project_organization/bundle_extension/install_package.md
+                - Upload on Packagist: administration/project_organization/bundle_extension/upload_packagist.md
         - Admin panel:
             - Admin panel: administration/admin_panel/admin_panel.md
             - Users: administration/admin_panel/users_admin_panel.md
@@ -761,6 +761,7 @@ nav:
         - Ibexa DXP PhpStorm plugin: resources/phpstorm_plugin.md
         - New in documentation: resources/new_in_doc.md
         - Contributing:
+
             - Report and follow issues: resources/contributing/report_and_follow_issues.md
             - Contribute translations: resources/contributing/contribute_translations.md
     - Release notes:

diff --git a/plugins.yml b/plugins.yml
@@ -466,7 +466,7 @@ plugins:
             'community_resources/phpstorm_plugin.md': 'resources/phpstorm_plugin.md'
             'community_resources/report_follow_issues.md': 'resources/contributing/report_and_follow_issues.md'
             'community_resources/translations.md': 'resources/contributing/contribute_translations.md'
-            'community_resources/package_structure.md': 'resources/contributing/package_structure.md'
+            'community_resources/package_structure.md': 'administration/project_organization/bundle_extension/package_structure.md'
 
             'updating/update_ibexa_dxp.md': 'update_and_migration/update_ibexa_dxp.md'
             'updating/from_1.x_2.x/update_from_1.x_2.x.md': 'update_and_migration/from_1.x_2.x/update_from_1.x_2.x.md'