diff --git a/doc/contributing/developing.md b/doc/contributing/developing.md index e8939eeca651aadf2bedef512ed8009df305b4aa..d00bb4fa6b6cd2fd87a556da8ea1649d1b37bbc9 100644 --- a/doc/contributing/developing.md +++ b/doc/contributing/developing.md @@ -1,89 +1,101 @@ # Developing -OpenSlice backend services are mainly implemented with Java 17 or above and Spring boot. +OpenSlice backend services are mainly implemented with Java 17 or above and Spring Boot. -OpenSlice uses various subsystems and depending on the module would you like to work, other subsystems must be present (you can disable them though in the code, e.g. at docker-compose.yaml file). +OpenSlice uses various subsystems and depending on the module would you like to work, other subsystems must be present *(you can disable them though in the code, e.g. at docker-compose.yaml file)*. -To get the latest development branch: -```bash -wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh -sudo ./deploy.sh develop #[or replace develop with other branch name] -``` +## General requirements -You may follow the [installation process](https://osl.etsi.org/documentation/develop/deployment/), as described at "develop" tagged documentation. +- Docker should be installed in your development environment +- Run the core subsystems (see [related](#contribute-to-a-subsystem) section) -To work on a specific subsystem e.g. org.etsi.osl.tmf.api, you must: -1a - Deploy only the core necessary subsystems through: -```bash -sudo docker compose --profile dev down;sudo docker compose --profile dev up -d --build -``` -> Note **--profile dev** that will only deploy the core dependency subsystems, instead of the whole OpenSlice. +## Version/release management -1b - Or alternatively, commend out the respective container from the docker-compose.yaml file, so as to deploy the whole OpenSlice, except the subsystem you want to work on, following the provided installation steps. +Check [this](https://nvie.com/posts/a-successful-git-branching-model/) nice article on how we develop and release versions. -2 - Clone the respective repository, e.g. https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop +We develop in the `develop` branch and follow a issue driven development model. -3 - Code :) +## Getting Started -## General requirements +To get the latest development branch, execute: -- Docker should be installed in your development environment -- Run the core subsystems (see above section) +```bash +wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh +sudo ./deploy.sh develop #[or replace develop with another branch name] +``` +You may follow the [installation process](https://osl.etsi.org/documentation/develop/deployment/), as described at `develop` tagged documentation. -## Slack +## Contribute to a subsystem -Feel free to join OpenSlice [Slack](https://openslice.slack.com) for any development oriented questions. +To work on a specific subsystem e.g. `org.etsi.osl.tmf.api`, you must: -## Examples of developing on specific subsystems +1. Deploy only the core necessary subsystems through: -### VNF/NSD Catalog Management and NSD Deployment API service + ```bash + sudo docker compose --profile dev down;sudo docker compose --profile dev up -d --build + ``` + > Note **--profile dev** that will only deploy the core dependency subsystems, instead of the whole OpenSlice. -Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop + *OR* -Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port. + Alternatively, comment out the respective container from the `docker-compose.yaml` file, so as to deploy the whole OpenSlice, except the subsystem you want to work on, following the provided installation steps. -Make sure that the core subsystems are up and running. +2. Clone the respective repository, for example: [https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop](https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop) (the clone URLs are available at this link) -Execute it with -```bash -mvn spring-boot:run -``` +3. Code! 😊 -For verification, Swagger API of the service is at `http://localhost:13000/osapi/swagger-ui/index.html`. -There, you may try there various REST actions and authenticate via the OAuth server without the use of the UI. +## Examples of developing on specific subsystems +### VNF/NSD Catalog Management and NSD Deployment API service -### VNF/NSD Catalog Management and NSD Deployment WEB UI service +You need to: -The Web UI is written in AngularJS. +1. Clone the repository: `https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop` -Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop +2. Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port. -By default the project org.etsi.osl.portal.api exposes the folder ../org.etsi.osl.portal.web/src/ in a folder testweb (Check class MvcConfig.java in org.etsi.osl.portal.api) for development. (In production nginx is used). Point your browser to `http://localhost:13000/osapi/testweb/index.html/` +3. Make sure that the core subsystems are up and running. -## Version/release management + Execute it with: + ```bash + mvn spring-boot:run + ``` -Check this nice article on how we develop and release versions. +> For verification, Swagger API of the service is at `http://localhost:13000/osapi/swagger-ui/index.html`. + There, you may try there various REST actions and authenticate via the OAuth server without the use of the UI. -https://nvie.com/posts/a-successful-git-branching-model/ +### VNF/NSD Catalog Management and NSD Deployment WEB UI service -We develop in the develop branch and follow a issue driven development model. +The Web UI is written in `AngularJS`. To run it: ---- -## Wishlist +1. Clone the repository: [https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop](https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop) (the clone URLs are available at that link) -Check also our wishlist of new features. You can add your own. + > By default the project `org.etsi.osl.portal.api` exposes the folder `../org.etsi.osl.portal.web/src/` in a folder testweb (check class `MvcConfig.java` in `org.etsi.osl.portal.api`) for development. (In production *nginx* is used) + +2. Point your browser to `http://localhost:13000/osapi/testweb/index.html/` + +## Reach us + +We are available on different channels. -See [Wishlist](./wishlist.md). +## Slack +Feel free to join OpenSlice's [Slack](https://openslice.slack.com) workspace for any development oriented questions (preferred). +## E-mail +If you are a member or a participant, you can also reach out on the `OSL_TECH` mailing list. +For administrative support, contact `SDGsupport@etsi.org`. +--- +## Wishlist +Check also our wishlist of new features. You can add your own. +See [wishlist](./wishlist.md). \ No newline at end of file diff --git a/doc/contributing/documenting.md b/doc/contributing/documenting.md new file mode 100644 index 0000000000000000000000000000000000000000..953be19943d91555115b99b8ac1db2aa09e0f8d0 --- /dev/null +++ b/doc/contributing/documenting.md @@ -0,0 +1,37 @@ + +# Documenting + +OpenSlice's documentation runs on [MkDocs](https://www.mkdocs.org/). + +> This page is a WIP. Updates are ongoing. + +## Eligibility + +Documenting OpenSlice is limited to active contributors. So, if you: +1. are an active member or participant; +2. wish to contribute to it; +3. you're ready! + +## Documentation System and Structure + +[MkDocs](https://www.mkdocs.org/) is a fast and simple static site generator that's geared towards building project documentation. Documentation source files are written in `Markdown`, and configured with a single `YAML` configuration file. Start by reading the [introductory tutorial](https://www.mkdocs.org/getting-started/), then check the [User Guide](https://www.mkdocs.org/user-guide/) for more information. + +## Getting Started + +To contribute to OpenSlice's documentation, you need to follow those easy steps: + +1. Clone the [repository](https://labs.etsi.org/rep/osl/documentation) with: + + ```bash + git clone https://labs.etsi.org/rep/osl/documentation.git + ``` + +2. Checkout the desired branch (don't forget to select one or make one!): + + ```bash + git checkout develop #[or another branch] + ``` + +3. Document (and commit)! 😊 + +> The documentation website supports branches, so your changes will be reflected in the corresponding branch.