Skip to content
Snippets Groups Projects
Commit 5cf24939 authored by Julien Satti's avatar Julien Satti :sparkles:
Browse files

Add documenting.md page, reformat developing.md with rich markdown

parent 46cb9df1
No related branches found
No related tags found
1 merge request!14Resolve "Creating Release 2024Q4 documentation"
Pipeline #10396 passed
# Developing # 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)*.
## General requirements
- Docker should be installed in your development environment
- Run the core subsystems (see [related](#contribute-to-a-subsystem) section)
## Version/release management
Check [this](https://nvie.com/posts/a-successful-git-branching-model/) nice article on how we develop and release versions.
We develop in the `develop` branch and follow a issue driven development model.
## Getting Started
To get the latest development branch, execute:
To get the latest development branch:
```bash ```bash
wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh 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] 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. You may follow the [installation process](https://osl.etsi.org/documentation/develop/deployment/), as described at `develop` tagged documentation.
## Contribute to a subsystem
To work on a specific subsystem e.g. `org.etsi.osl.tmf.api`, you must:
To work on a specific subsystem e.g. org.etsi.osl.tmf.api, you must: 1. Deploy only the core necessary subsystems through:
1a - Deploy only the core necessary subsystems through:
```bash ```bash
sudo docker compose --profile dev down;sudo docker compose --profile dev up -d --build 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. > Note **--profile dev** that will only deploy the core dependency subsystems, instead of the whole OpenSlice.
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. *OR*
2 - Clone the respective repository, e.g. https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop 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.
3 - Code :) 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)
## General requirements 3. Code! 😊
- Docker should be installed in your development environment
- Run the core subsystems (see above section)
## Slack
Feel free to join OpenSlice [Slack](https://openslice.slack.com) for any development oriented questions.
## Examples of developing on specific subsystems ## Examples of developing on specific subsystems
### VNF/NSD Catalog Management and NSD Deployment API service ### VNF/NSD Catalog Management and NSD Deployment API service
Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop You need to:
Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port. 1. Clone the repository: `https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop`
Make sure that the core subsystems are up and running. 2. Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port.
Execute it with 3. Make sure that the core subsystems are up and running.
Execute it with:
```bash ```bash
mvn spring-boot:run mvn spring-boot:run
``` ```
For verification, Swagger API of the service is at `http://localhost:13000/osapi/swagger-ui/index.html`. > 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. There, you may try there various REST actions and authenticate via the OAuth server without the use of the UI.
### VNF/NSD Catalog Management and NSD Deployment WEB UI service ### VNF/NSD Catalog Management and NSD Deployment WEB UI service
The Web UI is written in AngularJS. The Web UI is written in `AngularJS`. To run it:
Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop
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/`
## Version/release management
Check this nice article on how we develop and release versions. 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)
https://nvie.com/posts/a-successful-git-branching-model/ > 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)
We develop in the develop branch and follow a issue driven development model. 2. Point your browser to `http://localhost:13000/osapi/testweb/index.html/`
--- ## Reach us
## Wishlist
Check also our wishlist of new features. You can add your own. 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
# 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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment