forked from microsoft/semantic-kernel
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Java: ADR to define the folder structure to be used for the Java port (…
…microsoft#1547) ### Motivation and Context Please help reviewers and future users, providing the following information: 1. Why is this change required? The folder structure used in the Java port has diverged from that used in .Net. Some of the changes make sense i.e., are idiomatic Java and others we should review. ### Description ADR to define the folder structure to be used for the Java port. This includes a comparison of the current .Net and Java folder structures and proposal for the Java folder structure we should move towards. ### Contribution Checklist - [x] The code builds clean without any errors or warnings - [x] The PR follows SK Contribution Guidelines (https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) - [x] The code follows the .NET coding conventions (https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions) verified with `dotnet format` - [x] All unit tests pass, and I have added new tests where possible - [x] I didn't break anyone 😄
- Loading branch information
1 parent
b0bbdc1
commit c5abac0
Showing
1 changed file
with
106 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
--- | ||
# These are optional elements. Feel free to remove any of them. | ||
status: {proposed} | ||
date: 2013-06-19 | ||
deciders: shawncal,johnoliver | ||
consulted: | ||
informed: | ||
--- | ||
# Java Folder Structure | ||
|
||
## Context and Problem Statement | ||
|
||
A port of the Semantic Kernel to Java is under development in the `experimental-java` branch. The folder structure being used has diverged from the .Net implementation. | ||
The purpose of this ADR is to document the folder structure that will be used by the Java port to make it clear to developers how to navigate between the .Net and Java implementations. | ||
|
||
## Decision Drivers | ||
|
||
* Goal is to learn for SDKs that already have excellent multiple language support e.g., [Azure SDK](https://github.com/Azure/azure-sdk/) | ||
* The Java SK should follow the general design guidelines and conventions of Java. It should feel natural to a Java developer. | ||
* Different language versions should be consistent with the .Net implementation. In cases of conflict, consistency with Java conventions is the highest priority. | ||
* The SK for Java and .Net should feel like a single product developed by a single team. | ||
* There should be feature parity between Java and .Net. Feature status must be tracked in the [FEATURE_MATRIX](../../FEATURE_MATRIX.md) | ||
|
||
## Considered Options | ||
|
||
Below is a comparison of .Net and Java Folder structures | ||
|
||
```bash | ||
dotnet/src | ||
Connectors | ||
Extensions | ||
IntegrationTests | ||
InternalUtilities | ||
SemanticKernel.Abstractions | ||
SemanticKernel.MetaPackage | ||
SemanticKernel.UnitTests | ||
SemanticKernel | ||
Skills | ||
``` | ||
|
||
| Folder | Description | | ||
|--------------------------------|-------------| | ||
| Connectors | Parent folder for various Connector implementations e.g., AI or Memory services | | ||
| Extensions | Parent folder for SK extensions e.g., planner implementations | | ||
| IntegrationTests | Integration tests | | ||
| InternalUtilities | Internal utilities i.e., shared code | | ||
| SemanticKernel.Abstractions | SK API definitions | | ||
| SemanticKernel.MetaPackage | SK common package collection | | ||
| SemanticKernel.UnitTests | Unit tests | | ||
| SemanticKernel | SK implementation | | ||
| Skills | Parent folder for various Skills implementations e.g., Core, MS Graph, GRPC, OpenAI, ... | | ||
|
||
Some observations: | ||
|
||
* The `src` folder is at the very start of the folder structure, which reduces flexibility | ||
* The use of the `Skills` term is due to change | ||
|
||
```bash | ||
java | ||
api-test | ||
samples | ||
semantickernel-api | ||
semantickernel-bom | ||
semantickernel-connectors-parent | ||
semantickernel-core-skills | ||
semantickernel-core | ||
semantickernel-extensions-parent | ||
``` | ||
|
||
| Folder | Description | | ||
|-------------------------------------|-------------| | ||
| `api-test` | Integration tests and API usage example | | ||
| `samples` | SK samples | | ||
| `semantickernel-api` | SK API definitions | | ||
| `semantickernel-bom` | SK Bill Of Materials | | ||
| `semantickernel-connectors-parent` | Parent folder for various Connector implementations | | ||
| `semantickernel-core-skills` | SK core skills (in .Net these are part of the core implementation) | | ||
| `semantickernel-core` | SK core implementation | | ||
| `semantickernel-extensions-parent` | Parent folder for SK extensions e.g., planner implementation | | ||
|
||
Some observations: | ||
|
||
* Using lowercase folder name with the `-` delimiter is idiomatic Java | ||
* The `src` folders are located as close as possible to the source files e.g., `semantickernel-api/src/main/java`, this is idiomatic Java | ||
* Unit tests are contained together with the implementation | ||
* The samples are located within the `java` folder and each sample runs standalone | ||
|
||
## Decision Outcome | ||
|
||
Follow these guidelines: | ||
|
||
* The folder names will match those used (or planned for .Net) but in the idiomatic Java folder naming convention | ||
* Use `bom` instead of `MetaPackage` as the latter is .Net centric | ||
* Use `api` instead of `Abstractions` as the latter is .Net centric | ||
* Move `semantickernel-core-skills` to a new `plugins` folder and rename to `plugins-core` | ||
* Use the term `plugins` instead of `skills` and avoid introducing technical debt | ||
|
||
| Folder | Description | | ||
|----------------------------------|-------------| | ||
| `connectors` | Containing: `semantickernel-connectors-ai-openai`, `semantickernel-connectors-ai-huggingface`, `semantickernel-connectors-memory-qadrant`, ... | | ||
| `extensions` | Containing: `semantickernel-planning-action-planner`, `semantickernel-planning-sequential-planner` | | ||
| `integration-tests` | Integration tests | | ||
| `semantickernel-api` | SK API definitions | | ||
| `semantickernel-bom` | SK common package collection | | ||
| `semantickernel-core` | SK core implementation | | ||
| `plugins` | Containing: `semantickernel-plugins-core`, `semantickernel-plugins-document`, `semantickernel-plugins-msgraph`, ... | |