Skip to content
This repository has been archived by the owner on Apr 29, 2024. It is now read-only.

Commit

Permalink
[yaml] update repo README
Browse files Browse the repository at this point in the history 
for docs.microsoft.com/samples
  • Loading branch information
@conceptdev
conceptdev committed Aug 12, 2019
1 parent c1adb32 commit 60edc9f
Showing 1 changed file with 46 additions and 53 deletions.
99 changes: 46 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
Mac Samples
===========
# Mac Samples

Sample code for Xamarin's C# APIs to develop Mac applications. Visit the [Mac Sample Gallery](http://developer.xamarin.com/samples/mac/all) to download individual samples.
Sample code for Xamarin's C# APIs to develop Mac applications. Visit the [Mac Sample Gallery](https://docs.microsoft.com/samples/browse/?term=Xamarin.Mac) to download individual samples.

License
-------
## License

The Apache License 2.0 applies to all samples in this repository.

Expand All @@ -22,36 +20,35 @@ The Apache License 2.0 applies to all samples in this repository.
See the License for the specific language governing permissions and
limitations under the License.

Samples Submission Guidelines
=============================
## Samples Submission Guidelines

## Galleries
### Galleries

We love samples! Application samples show off our platform and provide a great way for people to learn our stuff. And we even promote them as a first-class feature of the docs site. You can find our sample galleries here:

* [Xamarin Forms Samples](http://developer.xamarin.com/samples/xamarin-forms/all/)
- [Xamarin.Forms Samples](https://docs.microsoft.com/samples/browse/?term=Xamarin.Forms)

* [iOS Samples](http://developer.xamarin.com/samples/ios/all/)
- [iOS Samples](https://docs.microsoft.com/samples/browse/?term=Xamarin.iOS)

* [Mac Samples](http://developer.xamarin.com/samples/mac/all/)
- [Mac Samples](https://docs.microsoft.com/samples/browse/?term=Xamarin.Mac)

* [Android Samples](http://developer.xamarin.com/samples/android/all/)
- [Android Samples](https://docs.microsoft.com/samples/browse/?term=Xamarin.Android)

## Sample GitHub Repositories

These sample galleries are populated by samples in these GitHub repos:

* [https://github.com/xamarin/xamarin-forms-samples](https://github.com/xamarin/xamarin-forms-samples)
- [https://github.com/xamarin/xamarin-forms-samples](https://github.com/xamarin/xamarin-forms-samples)

* [https://github.com/xamarin/mobile-samples](https://github.com/xamarin/mobile-samples)
- [https://github.com/xamarin/mobile-samples](https://github.com/xamarin/mobile-samples)

* [https://github.com/xamarin/monotouch-samples](https://github.com/xamarin/monotouch-samples)
- [https://github.com/xamarin/monotouch-samples](https://github.com/xamarin/ios-samples)

* [https://github.com/xamarin/mac-samples](https://github.com/xamarin/mac-samples)
- [https://github.com/xamarin/mac-samples](https://github.com/xamarin/mac-samples)

* [https://github.com/xamarin/monodroid-samples](https://github.com/xamarin/monodroid-samples)
- [https://github.com/xamarin/monodroid-samples](https://github.com/xamarin/monodroid-samples)

* [https://github.com/xamarin/mac-ios-samples](https://github.com/xamarin/mac-ios-samples)
- [https://github.com/xamarin/mac-ios-samples](https://github.com/xamarin/mac-ios-samples)

The [mobile-samples](https://github.com/xamarin/mobile-samples) repository is for samples that are cross-platform.
The [mac-ios-samples](https://github.com/xamarin/mac-ios-samples) repository is for samples that are Mac/iOS only.
Expand All @@ -62,62 +59,58 @@ We welcome sample submissions, please start by creating an issue with your propo

Because the sample galleries are powered by the github sample repos, each sample needs to have the following things:

* **Screenshots** - a folder called Screenshots that has at least one screen shot of the sample (preferably a screen shot for every page or every major functionality piece, people really key off these things). for the xplat samples, the folder should be split into platform folders, e.g. iOS, Android, Windows. see[ https://github.com/xamarin/mobile-samples/tree/master/Tasky/Screenshots](https://github.com/xamarin/mobile-samples/tree/master/Tasky/Screenshots) for an example of this.
- **Screenshots** - a folder called Screenshots that has at least one screen shot of the sample on each platform (preferably a screen shot for every page or every major piece of functionality). For an example of this, see [HeartRateMonitor](https://github.com/xamarin/mac-samples/tree/master/HeartRateMonitor/Screenshots).

* **Readme** - a[ README.md](http://readme.md/) file that has the name of the sample, a description, and author attribution. sample here:[ https://github.com/xamarin/mobile-samples/blob/master/Tasky/README.md](https://github.com/xamarin/mobile-samples/blob/master/Tasky/README.md)
- **Readme** - a `README.md` file that explains the sample, and contains metadata to help customers find it. For an example of this, see [HeartRateMonitor](https://github.com/xamarin/mac-samples/tree/master/HeartRateMonitor/README.md). The README file should begin with a YAML header (delimited by `---`) with the following keys/values:

* **Metadata** - Finally, it needs a Metadata.xml file ([https://github.com/xamarin/mobile-samples/blob/master/Tasky/Metadata.xml](https://github.com/xamarin/mobile-samples/blob/master/Tasky/Metadata.xml)) that has some information:
- **name** - must begin with `Xamarin.Mac -`

* **ID** - A GUID for the sample. You can generate this in MD under Tools menu : Insert GUID. we need this to key between articles and their associated samples
- **description** - brief description of the sample (< 150 chars) that appears in the sample code browser search

* **IsFullApplication** - Boolean flag (true or false): whether or not this is a full application such as the MWC App, Tasky, etc., or it's just a feature sample, such as, how to use 'x' feature. the basic test here is, if you would submit this to the app store because it's useful, then it's a full app, otherwise it's just a feature sample.
- **page_type** - must be the string `sample`.

* **Brief** - Short description or what your sample does. This allows us to display a nice and clean vignette on the sample page.
- **languages** - coding language/s used in the sample, such as: `csharp`, `fsharp`, `vb`, `objc`

* **Level** - Beginning, Intermediate, or Advanced: this is the intended audience level for the sample. only the getting started samples are Beginning, as they are intended for people who are _just_ starting with the platform. most samples are Intermediate, and a few, that dive deep into difficult APIs, should be Advanced.
- **products**: should be `xamarin` for every sample in this repo

* **Minimum License Requirement** - Starter, Indie, Business, or Enterprise: denotes the license that a user has to have in order to build/run the sample.
- **urlFragment**: although this can be auto-generated, please supply an all-lowercase value that represents the sample's path in this repo, except directory separators are replaced with dashes (`-`) and no other punctuation.

* **Tags**: a list of relevant tags for the app. These are:
* **Data**
* **Games**
* **Graphics** (CoreDrawing, Animation, OpenGL...)
* **Media** (Video, Sound, recording, photos)
* **Platform Features** (Photo Library, Contacts, Calendars, etc.)
* **Device Features** (NFC, Accelerometer, Compass, Magnemometer, Bluetooth, RFID)
* **Cloud** (Web Services, Networking, etc.)
* **Backgrounding**
* **Maps + Location**
* **Binding + Interop** (Projections)
* **Notifications**
* **Touch**
* **Getting Started**
* **Async**
* **Extension**
* **SceneKit**
* **FSharp**
* **Yosemite**
* **El Capitan**
Here is a working example from [_HeartRateMonitor_ README raw view](https://raw.githubusercontent.com/xamarin/mac-samples/master/HeartRateMonitor/README.md/README.md).

* **SupportedPlatforms**: this is only for cross plat samples. It's a comma-separated list, and the valid values are iOS, Android, and Windows.
```yaml
---
name: Xamarin.Mac - HeartRateMonitor
description: The CoreBluetooth framework provides the classes needed for your iOS and Mac apps to communicate with devices that are equipped with Bluetooth low...
page_type: sample
languages:
- csharp
products:
- xamarin
urlFragment: heartratemonitor
---
# Heading 1

* **Gallery**: This tag must contain a value of true if you want the sample to show up in the samples gallery on the developer portal.
rest of README goes here, including screenshot images and requirements/instructions to get it running
```

* **Buildable Sln and CSProj file** - the project _must_ build and have the appropriate project scaffolding (solution + proj).
> NOTE: This must be valid YAML, so some characters in the name or description will require the entire string to be surrounded by " or ' quotes.

A good example of this stuff is here in the drawing sample:[ https://github.com/xamarin/monotouch-samples/tree/master/Drawing](https://github.com/xamarin/monotouch-samples/tree/master/Drawing)
- **Buildable solution and .csproj file** - the project _must_ build and have the appropriate project scaffolding (solution + .csproj files).

This approach ensures that all samples integrate with the Microsoft [sample code browser](https://docs.microsoft.com/samples/browse/?term=Xamarin.Mac).

A good example of this stuff is here in the [HeartRateMonitor](https://github.com/xamarin/mac-samples/blob/master/HeartRateMonitor/)

For a cross-platform sample, please see: https://github.com/xamarin/mobile-samples/tree/master/Tasky

## GitHub Integration

We integrate tightly with Git to make sure we always provide working samples to our customers. This is achieved through a pre-commit hook that runs before your commit goes through, as well as a post-receive hook on GitHub's end that notifies our samples gallery server when changes go through.

To you, as a sample committer, this means that before you push to the repos, you should run the "install-hook.bat" or "install-hook.sh" (depending on whether you're on Windows or OS X/Linux, respectively). These will install the Git pre-commit hook. Now, whenever you try to make a Git commit, all samples in the repo will be validated. If any sample fails to validate, the commit is aborted; otherwise, your commit goes through and you can go ahead and push.
To you, as a sample committer, this means that before you push to the repos, you should run the "install-hook.bat" or "install-hook.sh" (depending on whether you're on Windows or macOS/Linux, respectively). These will install the Git pre-commit hook. Now, whenever you try to make a Git commit, all samples in the repo will be validated. If any sample fails to validate, the commit is aborted; otherwise, your commit goes through and you can go ahead and push.

This strict approach is put in place to ensure that the samples we present to our customers are always in a good state, and to ensure that all samples integrate correctly with the sample gallery (README.md, Metadata.xml, etc). Note that the master branch of each sample repo is what we present to our customers for our stable releases, so they must *always* Just Work.

Should you wish to invoke validation of samples manually, simply run "validate.windows" or "validate.posix" (again, Windows vs OS X/Linux, respectively). These must be run from a Bash shell (i.e. a terminal on OS X/Linux or the Git Bash terminal on Windows).
Should you wish to invoke validation of samples manually, simply run "validate.windows" or "validate.posix" (again, Windows vs macOS/Linux, respectively). These must be run from a Bash shell (i.e. a terminal on macOS/Linux or the Git Bash terminal on Windows).

If you have any questions, don't hesitate to ask!

0 comments on commit 60edc9f

Please sign in to comment.