Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update contribution instructions, 1st cut at readme templates #1

Merged
merged 1 commit into from
Oct 4, 2024
Merged

Update contribution instructions, 1st cut at readme templates #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 99 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Contribution Guidance

This is a community repository for sample Microsoft 365 Copilot agents developed using code-first approaches using tools such as Visual Studio Code and Teasm Toolkit.

If you'd like to contribute to this repository, please read the following guidelines. Contributors are more than welcome to share their learnings with others in this centralized location.

## Code of Conduct
Expand Down Expand Up @@ -71,6 +73,103 @@ When you submit a new sample, please follow these guidelines:
* You can add as many screen shots as you'd like to help users understand your sample without having to download it and install it.
* You can include animated images (such as `.gif` files), but you must provide at least one static `.png` file

## Sample naming and file structure

New sample submissions must follow these naming and structure guidelines:

### 1. Folder

Each sample should be in its own folder within the /samples directory. Your folder name should include a prefix depending on the type of sample, as follows:

| Prefix | Description |
| --- | --- |
| cea- | These are Custom engine agents that interact with users in the Bizchat chat surface via the Azure Bot Framework |
| da - | These are Declarative agents that run using Microsoft 365 Copilot's AI and orchestration and may include API plugins and Graph connectors |
| msgext- | These are agents implemented as Microsoft 365 Message extensions |

### 2. README.md file

Your sample folder should contain a `README.md` file for your contribution. Please base your `README.md` file on one of the following templates:

| If your sample is | use this template |
| --- | --- |
| built with Teams Toolkit for VS Code | [README.md](/samples/_SAMPLE_templates/ttk-vs-code-sample/README.md) |
| built with Teams Toolkit for Visual Studio | [README.md](/samples/_SAMPLE_templates/ttk-vs-sample/README.md) |
| something else | [README.md](/samples/_SAMPLE_templates/any-sample/README.md) |

Please copy the template to your project and update it accordingly. Your `README.md` must be named exactly `README.md` -- with capital letters -- as this is the information we use to make your sample public.

Each README.md file must contain detailed build and use instructions.

### 3. .gitignore

The [.gitignore](https://git-scm.com/docs/gitignore) file controls which files are ignored, to prevent checking in files that are part of packages and other files generated at build time.

Since the samples are built with a variety of toolchains, it is not possible to have a global .gitignore file that will work with all of them. So please be sure to include a .gitignore file in your sample folder that will ignore anything that will be downloaded or created locally when building your solution.

| If your sample is | sample gitignore |
| --- | --- |
| built with Teams Toolkit | no sample needed - file is generated by Teams Toolkit |
| a Web service based on .NET | [.gitignore](/samples/_SAMPLE_templates/dotnet-sample/.gitignore) |
| a Web service based on nodeJS | [.gitignore](/samples/_SAMPLE_templates/node-sample/.gitignore) |
| something else | You may find [these samples](https://github.com/github/gitignore) to be helpful |

This is also a good time to check to make sure you have removed any secrets or tenant-specific settings from your sample such as application IDs and secrets.

### 4. Handling environment variables

Environment variables are often stored in files such as **.env**, **.env.local**, or **appSettings.json**. If they aren't already, consider adding these files to your .gitignore and providing sample files instead.

> Special note for projects using [Teams Toolkit for Visual Studio Code](https://aka.ms/teams-toolkit): The .gitignore file generated by Teams Toolkit does not exclude the dev environment file (**env\.env.dev**) to facilitate sharing dev settings among a team. For your sample please make sure you don't check your tenant-specific settings in, and be aware they may have been put there during provisioning by Teams Toolkit. Feel free to add this file to .gitignore.

It's a good idea to provide sample files so people know what's required to run your solution. For example you might provide an **.env.local.sample** file like this:

```text
# Generated during provision
BOT_ID=
TEAMS_APP_ID=
BOT_DOMAIN=
BOT_ENDPOINT=

# Set by the developer
OPENAI_API_ENDPOINT=https://api.openai.com/v1/chat/completions
OPENAI_MODEL=text-davinci-03
```
and **.env.local.user.sample** like this:

```text
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The instructions would tell developers to copy the **.env.local.sample** to a new file **.env.local**, and to also copy **.env.local.user.sample** to **.env.local.user**, and then to fill in certain values.

Notice that:

* Values generated by Teams Toolkit, such as BOT_ID, are blank. Teams Toolkit will generate new values and fill them in during provisioning.
* Values that are likely to work for all developers are filled in, and
* Values to be provided manually by each developer are shown with the details removed to convey the format while not revealing the sample author's personal settings.

### 5. Screen shot

You will need to have a screenshot picture of your sample in action in the `README.md` file ("pics or it didn't happen"). This is manditory since we've found that users tend not to try samples that lack a screen shot. Please use a standard format such as .png, .jpg, or .gif for your screen shot so it will work in various places, such as in the [sample browser](https://adoption.microsoft.com/en-us/sample-solution-gallery/){target=_blank}. Animated .png or .gif files are welcome.

The preview image must be located in the `/assets/` folder in the root your solution. Even if it's a simple bot sending a single chat message, please include a screen shot!

### 6. M365 App manifest

Your sample should include a clearly marked folder containing a Teams/M365 `manifest.json` file and well-formed application icons along with any additional files such as declarative agent and API plugin JSON files.

* If the manifest works as-is, you may optionally include an installable Teams application package (zip archive containing these files).

* If the `manifest.json` requires modification before use, please do not include a zip archive. Instead, include instructions in your `README.md` file explaining how to modify the manifest and create the Teams application package

### 7. Telemetry

Each `README` template contains a specific tracking image at the bottom of the file with an `img` tag, where the `src` attribute points to `https://m365-visitor-stats.azurewebsites.net/teams-dev-samples/samples/xxx`. This is a transparent image which is used to track viewership of individual samples in GitHub. We only count the number of times each page is accessed, and capture no personal information or correlation with other pages.

Please update the image `src` attribute according with the repository name and folder information. For example, if your sample is named `bot-todo` in the `samples` folder, you should update the `src` attribute to `https://m365-visitor-stats.azurewebsites.net/sp-dev-fx-webparts/samples/bot-todo`.


## Submitting Pull Requests

> If you aren't familiar with how to contribute to open-source repositories using GitHub, or if you find the instructions on this page confusing, [sign up](https://forms.office.com/Pages/ResponsePage.aspx?id=KtIy2vgLW0SOgZbwvQuRaXDXyCl9DkBHq4A2OG7uLpdUREZVRDVYUUJLT1VNRDM4SjhGMlpUNzBORy4u) for one of our [Sharing is Caring](https://pnp.github.io/sharing-is-caring/#pnp-sic-events) events. It's completely free, and we'll guide you through the process.
Expand Down
67 changes: 67 additions & 0 deletions samples/_SAMPLE_templates/any-sample/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# title of the sample

_Thank you for using this template. Please edit the file as needed, following the structure as much as possible so the samples are consistent._

_Notes to the submitter (you) are in italics; please delete them before submitting._

_Thanks! Sharing is caring!_

## Summary

Short summary on functionality and used technologies.

![picture of the app in action](#)

## Frameworks

_If you use the Bot framework SDK, please replace x.y in the URL below to indicate the version_

![drop](https://img.shields.io/badge/Bot Framework-x.y-green.svg)

_If you use any other frameworks or platforms, please add badges for them here. If there are spaces in the framwork name, use  ._

![drop](https://img.shields.io/badge/.NET Core-x.y-green.svg)

## Prerequisites

* [Office 365 tenant](https://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment)
* [Whatever](#)

_Please list any portions of the toolchain required to build and use the sample, along with download links_

## Version history

Version|Date|Author|Comments
-------|----|----|--------
1.0|August 29, 2025|Parker PnP|Initial release

## Disclaimer

**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**

---

## Minimal Path to Awesome

_Include consise instructions to set up and run the sample. These are just an example!_

* Clone this repository
* Start ngrok? Note the URL and update it where?
* Register a bot or Azure AD application? (how?)
* Update the manifest (how?) and upload to Teams
* in the command line run:
* `somepackagemanager installcommand`
* `sometaskrunner command`

## Features

Description of the web part with possible additional details than in short summary.
This Web Part illustrates the following concepts on top of the SharePoint Framework:

* topic 1
* topic 2
* topic 3

_Below there is a clear image used for telemetry. Please change "readme-template" to your sample name._

<img src="https://m365-visitor-stats.azurewebsites.net/sp-dev-fx-webparts/samples/readme-template" />
Loading
Loading