Development

In general our O2A software is open source, free of charge and may be re-used in other contexts. Our software is administrated in the gitlab.awi.de repository and you can also find examples on github.com. To foster and streamline software development we want to have one central managed code basis. All splitted branches for new features and bug fixes shall be finally merged into the central main branch.

We are developing our software solutions mainly in two-weekly increment phases following an agile approach. Each phase starts and ends with an increment meeting. The increment meeting consists of

• review including a demonstration of achivements,
• planning and priorization of tasks for the next two weeks, and
• retrospective to improve the development process.

Review and planning are open for everyone interested. No detailed discussions. Please read how you can contribute. For user feedback on portal and viewer, visit our Jour Fixe.

The retrospective is reserved for development team members.

Read about collaboration meetings in the organisation section.

License

Our O2A software is licensed under BSD-3-Clause, if no other definition is given. To foster community value, we encourage you to use also BSD-2-Clause, BSD-3-Clause or MIT licences for your derived works. We will only integrate your work into our managed code basis, if it is licensed the way described before. 3rd-party libraries keep their licences and must be compatible with named licenses.

Standards

Our software development follows simple rules as best practices. Use the following topics and tasks as guideline and checklist.

Versioning

• [ ] Use Git. gitlab.awi.de.
• [ ] Commit and push your daily work.
• [ ] Use Gitflow semantics to structure contributions aligned with tickets.
• [ ] Each repository must have a README.md markdown file in its root directory describing the project.
• [ ] Each repository must have a .gitignore file in its root directory defining files to exclude or to force inclusion.

Ticketing

• [ ] Document and describe your work and requirements in stories, tasks and bugs. - gitlab.awi.de.
• [ ] Define a definition of done.
• [ ] Put new things into the backlog.
• [ ] Define a definition of ready, when do you can start to work on a ticket.
• [ ] Estimate the effort for a ticket.
• [ ] Only ready tickets go into an increment.
• [ ] Optionally, set the software version to a ticket.
• [ ] Keep track of progress and log your work.
• [ ] Documentation and tests are part of the work within a ticket.
• [ ] Check definition of done, then done.

Documentation

• [ ] Provide an up-to-date description of the project. README.md.
• [ ] Provide a "getting started" description for developers. README.md.
• [ ] Provide a "deployment" description for developers to setup. README.md.
• [ ] Create architecture and relationship diagrams where really necessary to provide an overview for others.
• [ ] Use simple diagrams - blocks and edges - where useful and provided editable formats. Best go for diagrams.net.
• [ ] For details use UML standardized diagrams. Best go for diagrams.net.
• [ ] Document and comment your code. It's part of your daily work.
• [ ] Provide admin documentation to setup the project including configuration description.
• [ ] Provide usage and API documentation for end users. Be clear, not technical.
• [ ] For web services use OpenAPI documentation.

Code style

• [ ] Align your code structure and documentation to Google Style Guides.
• [ ] Document your code short and clear. Your (not involved) colleague should easily jump in.
• [ ] Use Editorconfig and place a .editorconfig file in your project root to force basic code styling.

Languages

We focus on specific languages for client-side and server-side developments and data processing. We try to keep dependencies to 3rd-party libraries as low as possible. These decisions are based on a trade-off estimate between effort and sustainability. So take the following points as guideline.

Client-side

• [ ] Use basic JavaScript supported features.
• [ ] Follow the JavaScript, HTML/CSS code style guides.
• [ ] Don't get for 3rd-party libraries for simple and standard functions if not required. Discuss the trade-off.
• [ ] Use JavaScript modules where ever possible and useful. Keep an eye on re-usability and usage in other contexts.
• [ ] Provide an index.js in module directories to bundle useful module classes.
• [ ] Always provide JSDoc for classes, methods and integrations. Don't comment every line or simple getters and setters.
• [ ] Use primary used frameworks: Vue.js, Bootstrap, Leaflet, D3.js, Plotly, jQuery. Discuss using frameworks like React or similar.
• [ ] Use bundling tools for web-optimizing, not for primary development.

Server-side

• [ ] Use Java for middleware and backend.
• [ ] Follow the Java code style guide.
• [ ] Use Maven for dependency and build management.
• [ ] Always provide Javadoc for classes, methods and integrations. Don't comment every line or simple getters and setters.
• [ ] Use primary defined standards and long-term sustained libraries, e.g. Jakarta Persistence API with Hibernate implementation.
• [ ] Use logging libraries for system outputs and write to files, e.g. Log4j.
• [ ] Install snapshots and releases to Gitlab package manager.

Of course other languages are possible. But we clearly focus on Java. For example you can use PHP for simple web application or portal tasks. But don't develop heavy software. Even if you go with Laravel or similar. Use Composer for dependency management.

Processing

• [ ] Use Python for data processing and automation tasks.
• [ ] Follow the Python code style guide.
• [ ] Use virtual environments for dependencies with pip or conda.
• [ ] Provide a requirements.txt file in the project repository root directory.
• [ ] Always provide comments for classes, methods and integrations. Don't comment every line or simple getters and setters.
• [ ] Use primary used libraries and sustained libraries, e.g. pandas, requests, tensorflow.
• [ ] Use logging for system outputs and write to files.

Tests

• [ ] Tests exists for my commit?
• [ ] Write unit tests for methods and critical workflows.
• [ ] Write integration and system tests from frontend (grey) to backend (black).
• [ ] Check requirements for development, test and production environment.
• [ ] Use Gitlab Continuous Integration pipeline.

Conventions

Project and repository names

• [ ] Always define a namespace for the project like o2a. for e.g. o2a.registry.core.

Software versions

• [ ] Make sure your version covers also documentation and tests.
• [ ] Use the Semantic Versioning paradigm.
• [ ] Use 0.x.y as major version during initial development phase.
• [ ] Use version 1.0.0 as the official first public release.
• [ ] Don't prepend "v" or similar to a version.

Commit messages

• [ ] Each commit must relate to a ticket.
• [ ] Use the ticket ID and short description syntax for commits. For example (#134) Fixed dragging of tiles
• [ ] If multiple tickets need to get references, add the uppercase ticket IDs in the body of the commit message.

Branch names

• [ ] Use Gitflow syntax and semantics.
• [ ] Each feature, bugfix, hotfix branch requires a ticket.
• [ ] Prepare release branches with the defined software version.

main
dev
feature/[ticket ID]_[short_name] - Use underscores. For example: feature/312_create_versions
bugfix/[ticket ID]_[short_name] - Use underscores. For example: bugfix/134_tile_dragging
hotfix/[ticket ID]_[short_name] - Use underscores. For example: hotfix/134_tile_dragging
release/[version] - For example release/1.24.3