Update documentation

3 Setup instructions/00040-SetupDevelopmentEnvironment.md

@@ -1,15 +1,16 @@
 ## Setup Oskari development environment
 
-This document describes how to setup development environment for Oskari using source code. If you want to develop / maintain oskari yourself this is the correct section.
-For setting up an instance using the ready jetty bundle check out [Setup Jetty](00030-SetupJetty.md)
+This section describes how to setup development environment for Oskari using source code. If you want to customize Oskari, this is the correct section.
+
+For setting up an instance using the ready Jetty bundle see [Setup Jetty](00030-SetupJetty.md)
 
 ### Requirements
 
-The following items are assumed installed.
+The following items are required for the development process:
 
 * JDK 8
 * [Maven 3+](http://maven.apache.org/) (developed using 3.5.0)
-* Git client (http://git-scm.com/) - Optionally download zip file from https://github.com/oskariorg/oskari-server
+* [Git client](http://git-scm.com/) (git is mandatory for contributing any changes to Oskari) - Optionally download zip file from [oskari-server GitHub repo](https://github.com/oskariorg/oskari-server)
 * `{jetty.base}` refers to the oskari-server folder in an unzipped [Jetty bundle](/download)
 
 ### Setup Git configuration
@@ -22,27 +23,31 @@ Ignore file permissions:
 
 ### Fetch Oskari-server source code
 
-With commandline git:
+With command line git:
 
     git clone https://github.com/oskariorg/oskari-server.git
 
-Note! You can also download the codes in zip format from Github, but for contributing any changes to Oskari git is mandatory.
-Additional Maven modules can be contributed outside git though if they are compatible with the current develop/master branch, but this is not adviced.
+Or download the codes in zip format from [GitHub](https://github.com/oskariorg/oskari-server).
+
+Additional Maven modules can be contributed outside git though if they are compatible with the current develop/master branch, but this is not advised.
 
 Note! The sample application, including its source code and build, is available in `{jetty.base}/sample-application` within the [Jetty bundle](/download). The Jetty bundle uses the pre-built code located in the `dist` folder. To update the sample application you can replace the contents of the `sample-application` folder with a clone from https://github.com/oskariorg/sample-application, and build the application following the instructions in its README.md file.
 
 ### Build Oskari server
 
-This will build all modules that Oskari server is composed of.
+Build all modules that Oskari server is composed of with the following command:
 
     cd oskari-server
     mvn clean install
 
 ### Fetch sample-server-extension source code and compile it
 
-To test your changes on a running web app you can use sample-server-extension to create a webapp using your modified version of oskari-server.
+To test your changes on a running web app you can use [sample-server-extension](https://github.com/oskariorg/sample-server-extension/) to create a web app using your modified version of oskari-server.
+
 Check that the oskari.version in pom.xml matches the project version of oskari-server you built.
 
+Download and install the sample-server-extension with the following commands:
+
     git clone https://github.com/oskariorg/sample-server-extension.git
     cd sample-server-extension
     mvn clean install

3 Setup instructions/00050-UpdatingOskariVersion.md

@@ -1,31 +1,41 @@
 ## Updating Oskari version
 
-Note! We are updating the frontend and server versions at the same time and for best compatibility it's best to use same version in both. Hotfix/patch versions might not always match but with version `major.minor.patch` the major and minor versions should match.
+This section guides you through updating your Oskari instance.
 
-### Migration and release notes
-
-Simply updating the version of Oskari dependency for the frontend and server and building new versions of your app/server is enough in most cases. But sometimes there are additional things that need to be done when updating. For example your application code might not compile after updating if we have changed some class in oskari-server that you are using directly in your app or there might be some things that should be done while updating that are not as obvious. These things are documented on the `Migration Guide` in oskari-server repository. You should also at least skim through the `Release notes` for both server and frontend to see if there are something that might affect your app. There might be a new implementation of a functionality/bundle that you want to use instead of the old one or things like this.
+We are updating the frontend and server versions **at the same time** and for the best compatibility **it's best to use same version in both**. Hotfix/patch versions might not always match but with version `major.minor.patch` the major and minor versions should match.
 
-So take a look at these before updating:
+Before updating, the following links are recommended to at least skim through:
 
 - [Migration Guide](https://github.com/oskariorg/oskari-server/blob/master/MigrationGuide.md)
 - [Server release notes](https://github.com/oskariorg/oskari-server/blob/master/ReleaseNotes.md)
 - [Frontend release notes](https://github.com/oskariorg/oskari-frontend/blob/master/ReleaseNotes.md)
 
+### Migration and release notes
+
+In most cases updating Oskari version means:
+1. updating the version of Oskari dependency for the frontend and server and 
+2. building new versions of your app/server 
+
+Sometimes there are additional things that need to be done when updating. These are documented on [The Migration Guide in oskari-server repository](https://github.com/oskariorg/oskari-server/blob/master/MigrationGuide.md).
+
+There can be also application spesific things that need to be taken into account when updating. For example, your application code might not compile after updating if you have changed some class in oskari-server that you are using directly in your app.
+
+You should also at least skim through [the Release notes](https://oskari.org/documentation/docs/latest/12-Changelog) for both the server and the frontend to see if there is something that might affect your app. There might be, for example, a new implementation of a bundle/functionality that you want to use instead of the old one.
+
 It's also a good idea to see any PRs/changes for the sample application to see if there are things that you can streamline/change in your application for the newer version:
 
 - https://github.com/oskariorg/sample-application
 - https://github.com/oskariorg/sample-server-extension
 
 Note! The idea is not that you use the sample-application/server directly but use it as a template to create your own app/server. For example the database migrations in server-template assume they are run on an empty database and might not work properly if copied directly to your server code. We change the sample migrations between versions to make the most sense as simple examples for the latest version while actual apps (copies of sample-server) should work to migrate the existing database of the app.
 
-### Server
+### Updating the server
 
 Updating an Oskari-powered server that is based on the [sample-server-extension](https://github.com/oskariorg/sample-server-extension) template is done by updating the value of `oskari.version` property in [pom.xml](https://github.com/oskariorg/sample-server-extension/blob/1.2.1/pom.xml#L13) file:
 
 ```
     <properties>
-        <oskari.version>1.55.1</oskari.version>
+        <oskari.version>1.0.0</oskari.version>
         ...
     </properties>
 ```
@@ -34,42 +44,44 @@ To the new version:
 
 ```
     <properties>
-        <oskari.version>1.56.0</oskari.version>
+        <oskari.version>1.0.1</oskari.version>
         ...
     </properties>
 ```
+
 After this run `mvn clean install` to generate a new `oskari-map.war` under `[your-server-repository-root]/webapp-map/target`. Replace the `oskari-map.war` under the `oskari-server/webapps` folder (in a setup similar to the Oskari/Jetty download package) with the new one.
 
-### Frontend
+### Updating the frontend
 
 Updating an Oskari application that is based on the [sample-application](https://github.com/oskariorg/sample-application) template is fairly simple as well. For the frontend the oskari-frontend (and possible oskari-frontend-contrib) dependency is updated by changing the version number in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L9) file from the current version in the app:
+
 ```
   "dependencies": {
-    "oskari-frontend": "https://[email protected]/oskariorg/oskari-frontend.git#1.55.2"
+    "oskari-frontend": "https://[email protected]/oskariorg/oskari-frontend.git#1.0.0"
   },
 ```
 
 To the new version:
 
 ```
   "dependencies": {
-    "oskari-frontend": "https://[email protected]/oskariorg/oskari-frontend.git#1.56.0"
+    "oskari-frontend": "https://[email protected]/oskariorg/oskari-frontend.git#1.0.1"
   },
 
 ```
 
-When updating Oskari version you might also want to change the application version in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L3) on your application to signal that the application has been updated.
+When updating Oskari version, change also the application version in [package.json](https://github.com/oskariorg/sample-application/blob/1.2.1/package.json#L3) on your application to signal that the application has been updated.
 
 After this you need to run `npm install` to install any new/changed libraries and `npm run build` to generate a new build under `[your-application-repository-root]/dist/[version on package.json]`. After the build the application repository can be served as static resources from Jetty/nginx or similar server.
 
-Note! To use the newly built frontend you will need to update `oskari-ext.properties` under `oskari-server/resources` to link the new frontend version:
+Finally, to use the newly built frontend you will need to update `oskari-ext.properties` under `oskari-server/resources` to link the new frontend version:
 
       oskari.client.version=dist/[version from your package.json]
 
 
 #### Building the frontend for production
 
-Modern web applications are developed using JavaScript syntax that is not fully supported by older browsers and the code needs to be processed before it can be used by end-user browsers. This step also includes bundling and minifying the code so it's more compact for consumption than the human-friendly version that is used for development. This will reduce the startup time for the end-user dramatically.
+Modern web applications are developed using JavaScript syntax that is not fully supported by older browsers and the code needs to be processed before it can be used by the end-user browsers. This step also includes bundling and minifying the code so it's more compact for consumption than the human-friendly version that is used for development. This will reduce the startup time for the end-user dramatically.
 
 With the default sample application (a pre-built version is included in the zip download) you can run `npm run build` to generate the minified Javascript files. This will result in folders and files generated under `[your frontend repository root]/dist/`.
 

7 Operating instructions/00080-HowToUseABundle.md

@@ -1,18 +1,18 @@
 ### How to use a bundle
 
-A bundle is a component in an Oskari application. A bundle is a selection of [Oskari classes](00100-HowToUseClasses.md) which form a component that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. For a short introduction see [create your own bundle](/guides/quick-start/create-your-own-bundle).
+A bundle is a pluggable module in an Oskari application. A bundle is a selection of implementing JavaScript files that can include for example [Oskari classes](00100-HowToUseClasses.md) that as a whole form a module that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality - for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. For a short introduction see [create your own bundle](../8%20Developing%20instructions/00120-HowToCreateABundle.md).
 
 #### Directory structure
 
-See [here](../2 Application environment/00020-Frontend.md) for info about structure and conventions.
+See [here](../2%20Application%20environment/00040-DirectoryStructure.md) for information about directory structure and conventions.
 
 #### Implementation
 
-Bundles implementation files should be located under the `/bundles` folder. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is played) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. The bundle doesn't need to have an instance and can be just used to import dependency files that can be instantiated elsewhere. Usually you want to implement a BundleInstance since you can think of it as a starting point for your functionality which is triggered by just adding your bundle in an applications startup sequence.
+In oskari-frontend the implementations for bundles are be located under the `/bundles` folder. It's followed by a namespacing folder and a folder (usually) matching the bundle id. If the bundle has a BundleInstance (ie. something that is started/instantiated when the bundle is "played"/started) it is usually defined in a file called `instance.js`, but this is not enforced and any file referenced in bundle definition (`bundle.js`) can be used. 
 
-A Bundle instance is an Oskari class which implements `Oskari.bundle.BundleInstance` protocol. A Bundle instance is created as a result from a Bundle definitions (see above) create method. Bundle instance state and lifecycle is managed by Bundle Manager.
+A Bundle instance is an Oskari class which implements `Oskari.bundle.BundleInstance` protocol. Usually you want to implement a BundleInstance since you can think of it as a starting point for your functionality which is triggered by just adding your bundle in an applications startup sequence. A Bundle instance is created as a result from a Bundle definitions (see above) create method. Bundle instance state and lifecycle is managed by Bundle Manager. However, the bundle doesn't need to have an instance and can be just used to import dependency files that can be instantiated elsewhere. 
 
-Bundle lifecycle methods
+**Bundle lifecycle methods:**
 
 * `start` - called by application to start any functionality that this bundle instance might have
 * `update` - called by Bundle Manager when Bundle Manager state is changed (to inform any changes in current 'bundlage')
@@ -27,9 +27,17 @@ instance.mediator = {
 
 #### Definition
 
-The bundle definition (or package) should be located in `bundle.js` file under the `/packages` folder. The bundle package definition should not implement any actual functionality. It should only declare the JavaScript, CSS and localization resources (== files) and metadata if any. If the bundle package can be instantiated the package's `create` method should create the bundle's instance. The bundle doesn't need to have an instance and can be used to import dependency files that can be instantiated elsewhere. In that case the create method should return the bundle class itself (`return this;`).
+The bundle package definition should not implement any actual functionality. It should only declare the JavaScript, CSS and localization resources (= files) and metadata (if any). If the bundle package can be instantiated, the package's `create` method should create the bundle's instance. 
 
-[Sample bundle definition](/guides/quick-start/sample-bundle-definition)
+Usually the bundle definition (or package) is located in `bundle.js` file under the `/packages` folder. 
+
+As of 2024, the `bundle.js` file is used for
+1. picking what files need to be imported when a bundle with certain id is being used in the app
+2. define the way to include and split localization files when the application is built
+
+In this case, any CSS and most of Javascript can be imported on, from example, `instance.js`.
+
+If the bundle doesn't have an instance and is used to import dependency files that are instantiated elsewhere, the create method should return the bundle class itself (`return this;`). A sample bundle definition can be found as a file named `bundle.js` under `/packages/<mynamespace>/<bundle-identifier>/`.
 
 Bundle should install itself to Oskari framework by calling `installBundleClass` at the end of `bundle.js`
 

8 Developing instructions/00120-HowToCreateABundle.md

@@ -1,12 +1,14 @@
 ## How to create a bundle
 
-If you haven't done it already, download sources [here](). Then extract the files from the downloaded archive.
+If you haven't done it already, copy the oskari-frontend repo [here](https://github.com/oskariorg/oskari-frontend/).
 
-Now decide a `<bundle-identifier>` which is unique and describes the functionality the bundle offers e.g. 'search' (already implemented so prefix it with something like mysearch).
+Now decide a `<bundle-identifier>` which is unique and describes the functionality the bundle offers e.g. `search` (already implemented so prefix it with something like mysearch).
 
-Create a folder with the name of your `<bundle-identifier>` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework/<bundle-identifier>/resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. It is encouraged to create your own namespace (and directories) for your own bundles.
+Create a folder with the name of your `<bundle-identifier>` under `/packages/framework/` and `/bundles/framework/`. If you require styling/images, create a folder under `/bundles/framework/<bundle-identifier>/resources/css`, too. The `/framework/` directory isn't enforced and you can replace it with something fitting your bundle compilation. The `framework` directory refers to the namespace of the same name and it includes (almost) all code written by the Oskari core team. 
 
-Create a `bundle.js` file under `/packages/framework/<bundle-identifier>/`. You can use the following sample as a template.
+You can create your own namespace (and folders) for your own bundles. If you plan to contribute the bundle to oskari-frontend, place the bundle either to framework, mapping or admin depending on what the functionality is/does.
+
+Create a `bundle.js` file under `/packages/framework/<bundle-identifier>/`. You can use the sample file as a template (explained below).
 
 ### The Sample bundle