Skip to content

Commit 355eb68

Browse files
Merge branch 'microsoft:main' into update-modelid
2 parents 4277528 + f9bef63 commit 355eb68

111 files changed

Lines changed: 3735 additions & 1451 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/dotnet-format.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ jobs:
2626
matrix:
2727
include:
2828
#- { dotnet: '6.0', configuration: Release, os: ubuntu-latest }
29-
- { dotnet: '7.0', configuration: Release, os: ubuntu-latest }
30-
#- { dotnet: '8.0', configuration: Release, os: ubuntu-latest }
29+
#- { dotnet: '7.0', configuration: Release, os: ubuntu-latest }
30+
- { dotnet: '8.0', configuration: Release, os: ubuntu-latest }
3131

3232
runs-on: ${{ matrix.os }}
3333
env:

‎docs/FAQS.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Frequently Asked Questions
2+
3+
### How do I get access to nightly builds?
4+
5+
Nightly builds of the Semantic Kernel are available [here](https://github.com/orgs/microsoft/packages?repo_name=semantic-kernel).
6+
7+
To download nightly builds follow the following steps:
8+
9+
1. You will need a GitHub account to complete these steps.
10+
1. Create a GitHub Personal Access Token with the `read:packages` scope using these [instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).
11+
1. If you account is part of the Microsoft organization then you must authorize the `Microsoft` organization as a single sign-on organization.
12+
1. Click the "Configure SSO" next to the Person Access Token you just created and then authorize `Microsoft`.
13+
1. Use the following command to add the Microsoft GitHub Packages source to your NuGet configuration:
14+
15+
```powershell
16+
dotnet nuget add source --username GITHUBUSERNAME --password GITHUBPERSONALACCESSTOKEN --store-password-in-clear-text --name GitHubMicrosoft "https://nuget.pkg.github.com/microsoft/index.json"
17+
```
18+
19+
1. Or you can manually create a `NuGet.Config` file.
20+
21+
```xml
22+
<?xml version="1.0" encoding="utf-8"?>
23+
<configuration>
24+
<packageSources>
25+
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
26+
<add key="github" value="https://nuget.pkg.github.com/microsoft/index.json" />
27+
</packageSources>
28+
29+
<packageSourceMapping>
30+
<packageSource key="nuget.org">
31+
<package pattern="*" />
32+
</packageSource>
33+
<packageSource key="github">
34+
<package pattern="*nightly"/>
35+
</packageSource>
36+
</packageSourceMapping>
37+
38+
<packageSourceCredentials>
39+
<github>
40+
<add key="Username" value="<Your GitHub Id>" />
41+
<add key="ClearTextPassword" value="<Your Personal Access Token>" />
42+
</github>
43+
</packageSourceCredentials>
44+
</configuration>
45+
```
46+
47+
* If you place this file in your project folder make sure to have Git (or whatever source control you use) ignore it.
48+
* For more information on where to store this file go [here](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file).
49+
* You can also use the following command `he Microsoft GitHub Packages source can be added easier to NuGet:`
50+
1. You can now add packages from the nightly build to your project.
51+
* E.g. use this command `dotnet add package Microsoft.SemanticKernel.Core --version 0.26.231003.1-nightly`
52+
1. And the latest package release can be referenced in the project like this:
53+
* `<PackageReference Include="Microsoft.SemanticKernel" Version="*-*" />`
54+
55+
For more information see: <https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry>
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
# These are optional elements. Feel free to remove any of them.
3+
status: proposed
4+
contact: SergeyMenshykh
5+
date: 2024-01-04
6+
deciders: markwallace-microsoft
7+
consulted: rogerbarreto, dmytrostruk
8+
informed:
9+
---
10+
11+
# SK Branching Strategy
12+
13+
## Industry-adopted branching strategies
14+
There are several industry-adopted branching strategies for Git, such as GitHub Flow, Git-Flow, and GitLab Flow. However, we will only focus on the two most widely-used ones: GitHub Flow and Git-Flow.
15+
16+
### GitHub Flow
17+
GitHub Flow is a straightforward branching strategy that centres around the 'main' branch. Developers create a new branch for each feature or bugfix, make changes, submit a pull request, and merge the changes back to the 'main' branch. Releases are done directly from the 'main' branch, making this model ideal for projects with continuous integration/deployment. Learn more about [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow).
18+
19+
<img src="./diagrams/git-hub-flow.png" alt="GitFlow" width="500"/>
20+
21+
[Image source](https://www.abtasty.com/blog/git-branching-strategies/)
22+
23+
Pros:
24+
- Straightforward with fewer branches to manage and less merge conflicts.
25+
- No long running development branches.
26+
27+
Cons:
28+
- Not as well organized as Git-Flow.
29+
- The 'main' branch can get cluttered more easily since it functions as both the production and development branch.
30+
31+
### Git-Flow
32+
Git-Flow is a branching strategy that organizes software development around two long-lived main branches, 'main' and 'develop', along with short-lived feature, release, and hotfix branches. Developers work on new features in feature branches, which are then merged into the 'develop' branch. When preparing for a release, to avoid blocking future release features, a release branch is created, and once finalized (testing & bug fixing), it is merged into both 'main' and 'develop'. Hotfix branches in Git Flow are created from the 'main' branch to address critical bug fixes and are subsequently merged back into both the 'main' and 'develop' branches. The actual release(deployable artifact) is done from the 'main' branch that is reflects actual production worthy official releases. Learn more about [Git-Flow](https://nvie.com/posts/a-successful-git-branching-model/).
33+
34+
<img src="./diagrams/git-flow.png" alt="GitFlow" width="700"/>
35+
36+
Pros:
37+
- Clear separation between code under development and production-ready code.
38+
- Efficient release management.
39+
40+
Cons:
41+
- More complex than GitHub Flow, which may be overwhelming for smaller teams or projects that do not require as much structure.
42+
- Less suited for projects that prioritize continuous deployment, as it emphasizes a more controlled release process.
43+
- Not ideal for projects with continuous deployment due to the overhead of managing multiple branches.
44+
- Spaghetti history in Git - [GitFlow considered harmful](https://www.endoflineblog.com/gitflow-considered-harmful)
45+
46+
# SK branching strategies
47+
Today, the SK SDK is available in three languages: .NET, Java and Python. All of them coexist in the same Git repository, organized under corresponding folders. However, the branching strategies for those differ.
48+
49+
For both .NET and Python versions, development takes place in short-lived topic branches that branch off the 'main' branch. These topic branches are merged back into the 'main' branch when features are considered production-ready through PR reviews, unit tests, and integration test runs. Releases are carried out directly from the 'main' branch. This approach aligns with the GitHub Flow branching strategy, with a minor deviation where releases are conducted weekly rather than being continuously deployed.
50+
51+
The Java version of SK adheres to the Git-Flow strategy by being developed in a dedicated development branch. Topic branches are created from the development branch and merged back through pull requests after unit tests and integration test runs. Release branches are also created from the development branch and merged to both the development branch and the 'main' one when a release is considered production-ready. This strategy deviates slightly from vanilla Git-Flow in that release artifacts are generated from release branches rather than from the 'main' branch.
52+
53+
## Decision Drivers
54+
- The strategy should be easy to implement and maintain without requiring significant investments.
55+
- The strategy should allow for maintaining several releases in parallel if required.
56+
- Ideally, the strategy is intuitive and simple so that everyone familiar with Git can adopt and follow it.
57+
- Ideally, all SK languages are able to adopt and use the same branching strategy.
58+
- Ability to continually deploy new release with minimal overhead.
59+
- Ability to release language versions independently and on different schedules.
60+
- Allow the .Net, Java and Python teams to be able to operate independently.
61+
- Ability to patch a release (for all languages).
62+
- Consolidation of PR's and Issues to simplify the triage and review process.
63+
64+
Another aspect to consider when deciding on a branching strategy for SK is access permissions and action scopes. GitHub does not allow enforcing access restrictions on just a part of a repository, such as a folder. This means that it is not possible to restrict SK .NET contributors from pushing Python PRs, which ideally should be done by the corresponding team. However, GitHub does allow assigning access permissions to a branch, which can be successfully leveraged if the appropriate strategy option is chosen. The similar issue occurs with GitHub's required actions/status checks, which can only be set at the branch level. Considering that development for .NET and Python takes place in the 'main' branch, and status checks are configured per branch rather than per folder, it is not possible to configure separate status checks for .NET and Python PRs. As a result, the same status check runs for both .NET and Python PRs, even though it may not be relevant to a specific language.
65+
66+
!["Net PR status checks"](./diagrams/net-pr-status-checks.png)
67+
68+
Regardless of the chosen strategy, it should be possible to support multiple versions of SK. For example, applying a bug fix or a security patch to released SK v1.1.0 and v2.4.0 should be feasible while working on v3.0.0. One way to achieve this would be to create a release branch for each SK release. So that the required patch/fix can be pushed to the branch and released from it. However, marking released commits with tags should suffice, as it is always possible to create a new branch from a tag retrospectively when needed, if at all. Existing release pipelines should accept a source branch as a parameter, enabling releases from any branch and not only from the 'main' one.
69+
70+
## Considered Options
71+
72+
### Repository per SK language
73+
This option suggests having a separate GitHub repository for each SK language. These repositories can be created under a corresponding organization. Development and releases will follow the GitHub flow, with new features and fixes being developed in topic branches that created from the 'main' branch and eventually merged back.
74+
75+
Pros:
76+
- Each repository will have only language-specific status checks and actions.
77+
- Branch commits and release history will not contain irrelevant commits or releases.
78+
- Utilizes the familiar GitHub Flow without Git-Flow overhead, resulting in a shorter learning curve.
79+
- Access permissions are limited to the specific owning team.
80+
81+
Cons:
82+
- There is an initial overhead in setting up the three repositories.
83+
- There may be potential ongoing maintenance overhead for the three repositories.
84+
- Secrets must be managed across three repositories instead of just one.
85+
- Each repo will have a backlog that will have to be managed separately.
86+
87+
### Branch per SK language
88+
This option involves having a dedicated, language-specific development branch for each SDK language: 'net-development', 'java-development', and 'python-development'. SDK Java is already using this option. Development and releases will follow the GitHub Flow, with new features and fixes being developed in topic branches that are branched off the corresponding language branch and eventually merged back.
89+
90+
Pros:
91+
- Simple, language specific, status checks, actions and rules configured per language branch.
92+
- Allow only teams that own language-specific branches to push or merge to them, rather than just approving PRs.
93+
- Branch commits history does not contain irrelevant commits.
94+
95+
Cons:
96+
- GitHub release history contains releases for all languages.
97+
- Language-specific branches may not be straightforward to discover/use.
98+
99+
This option has two sub-options that define the way the 'main' branch is used:
100+
1. The 'main' branch will contain general/common artifacts such as documentation, GitHub actions, and samples. All language folders will be removed from the 'main' branch, and it can be locked to prevent accidental merges.
101+
2. The 'main' branch will include everything that dev branches have for discoverability purposes. A job/action will be implemented to merge commits from dev branches to the 'main' branch. The number of common artifacts between SK languages should be minimized to reduce the potential for merge conflicts. A solution for the squash merge problem that SK Java is experiencing today should be found before deciding on the sub-option.
102+
103+
The second sub-option is preferred over the first one due to its discoverability benefits. There is no need to select a development branch in the GitHub UI when searching for something in the repository. The 'main' branch is selected by default, and as soon as the latest bits are in the branch, they can be found easily. This intuitive approach is familiar to many, and changing it by requiring the selection of a branch before searching would complicate the search experience and introduce frustration.
104+
105+
### All SK languages in the 'main'
106+
This option assumes maintaining the code for all SK languages - .NET, Java, and Python in the 'main' branch. Development would occur using typical topic branches, while releases would also be made from the 'main' branch. This is the strategy currently adopted by .NET and Python, and corresponds to the GitHub Flow.
107+
108+
Pros:
109+
- All code in one place - the 'main' branch.
110+
- Familiar GitHub Flow, no Git-Flow overhead - shorter learning curve.
111+
112+
Cons:
113+
- Branch commits/release history contains irrelevant commits/releases.
114+
- Complex and irrelevant GitHub status checks/actions.
115+
- PRs can be pushed by non-owner teams.
116+
117+
### Current 'Hybrid' approach
118+
This choice keeps the existing method used by SK. .NET and Python development is done in the 'main' branch using GitHub Flow, while Java development happens in the java-development branch following Git-Flow.
119+
120+
Pros:
121+
- No changes required.
122+
- Each SK language uses a strategy that is convenient for it.
123+
124+
Cons:
125+
- Branch commits/release history contains irrelevant commits/releases.
126+
- Complex and irrelevant GitHub status checks/actions.
127+
- PRs can be pushed by non-owner teams.
128+
129+
## Decision Outcome
130+
Chosen option: "Current 'Hybrid' approach" because it works with minor inefficiencies (such as cluttered release history and multi-language complex actions) and requires no investments now. Later, depending on the team size and the problems the team encounters with the "Current 'Hybrid' approach," we may consider either the 'Repository per SK language' option or the 'Branch per SK language' one.
191 KB
Loading
185 KB
Loading
69.2 KB
Loading

‎dotnet/Directory.Packages.props‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363
<PackageVersion Include="Microsoft.OpenApi" Version="1.6.11" />
6464
<PackageVersion Include="Microsoft.OpenApi.Readers" Version="1.6.11" />
6565
<PackageVersion Include="Google.Apis.CustomSearchAPI.v1" Version="[1.60.0.3001, )" />
66-
<PackageVersion Include="Grpc.Net.Client" Version="2.59.0" />
66+
<PackageVersion Include="Grpc.Net.Client" Version="2.60.0" />
6767
<PackageVersion Include="protobuf-net" Version="3.2.30" />
6868
<PackageVersion Include="protobuf-net.Reflection" Version="3.2.12" />
6969
<PackageVersion Include="CoreCLR-NCalc" Version="2.2.113" />

‎dotnet/SK-dotnet.sln‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,6 @@ EndProject
88
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{831DDCA2-7D2C-4C31-80DB-6BDB3E1F7AE0}"
99
EndProject
1010
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{FA3720F1-C99A-49B2-9577-A940257098BF}"
11-
ProjectSection(SolutionItems) = preProject
12-
..\samples\dotnet\Directory.Build.props = ..\samples\dotnet\Directory.Build.props
13-
..\samples\dotnet\Directory.Build.targets = ..\samples\dotnet\Directory.Build.targets
14-
..\samples\dotnet\Directory.Packages.props = ..\samples\dotnet\Directory.Packages.props
15-
EndProjectSection
1611
EndProject
1712
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KernelSyntaxExamples", "samples\KernelSyntaxExamples\KernelSyntaxExamples.csproj", "{47C6F821-5103-431F-B3B8-A2868A68BB78}"
1813
EndProject
@@ -29,6 +24,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
2924
..\.editorconfig = ..\.editorconfig
3025
..\.gitignore = ..\.gitignore
3126
Directory.Build.props = Directory.Build.props
27+
Directory.Build.targets = Directory.Build.targets
3228
Directory.Packages.props = Directory.Packages.props
3329
..\.github\workflows\dotnet-format.yml = ..\.github\workflows\dotnet-format.yml
3430
..\nuget.config = ..\nuget.config

‎dotnet/nuget/nuget-package.props‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,21 @@
11
<Project>
22
<PropertyGroup>
33
<!-- Central version prefix - applies to all nuget packages. -->
4-
<VersionPrefix>1.0.1</VersionPrefix>
4+
<VersionPrefix>1.1.0</VersionPrefix>
55

66
<PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix)</PackageVersion>
77
<PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)</PackageVersion>
88

99
<Configurations>Debug;Release;Publish</Configurations>
1010
<IsPackable>true</IsPackable>
1111

12+
<!-- Package validation. Baseline Version should be lower than current version. -->
13+
<PackageValidationBaselineVersion>1.0.1</PackageValidationBaselineVersion>
14+
<!-- Validate assembly attributes only for Publish builds -->
15+
<NoWarn Condition="'$(Configuration)' != 'Publish'">$(NoWarn);CP0003</NoWarn>
16+
<!-- Do not validate reference assemblies -->
17+
<NoWarn>$(NoWarn);CP1002</NoWarn>
18+
1219
<!-- Default description and tags. Packages can override. -->
1320
<Authors>Microsoft</Authors>
1421
<Company>Microsoft</Company>

‎dotnet/samples/KernelSyntaxExamples/Example09_FunctionTypes.cs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@ public static async Task RunAsync()
5252
await kernel.InvokeAsync(plugin[nameof(LocalExamplePlugin.TaskInjectingKernelWithInputTextAndStringResult)],
5353
new()
5454
{
55-
["textToSummarize"] = @"C# is a modern, versatile language by Microsoft, blending the efficiency of C++
56-
with Visual Basic's simplicity. It's ideal for a wide range of applications,
55+
["textToSummarize"] = @"C# is a modern, versatile language by Microsoft, blending the efficiency of C++
56+
with Visual Basic's simplicity. It's ideal for a wide range of applications,
5757
emphasizing type safety, modularity, and modern programming paradigms."
5858
});
5959

@@ -238,6 +238,7 @@ public async Task<string> TaskInjectingServiceSelectorWithStringResult(Kernel ke
238238
/// <summary>
239239
/// Example how to inject CultureInfo or IFormatProvider in your function
240240
/// </summary>
241+
[KernelFunction]
241242
public async Task<string> TaskInjectingCultureInfoOrIFormatProviderWithStringResult(CultureInfo cultureInfo, IFormatProvider formatProvider)
242243
{
243244
var result = $"Culture Name: {cultureInfo.Name}, FormatProvider Equals CultureInfo?: {formatProvider.Equals(cultureInfo)}";

0 commit comments

Comments
 (0)