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

Commit

Permalink
update readme, add templates
Browse files Browse the repository at this point in the history
  • Loading branch information
@conceptdev
conceptdev committed Jul 26, 2018
1 parent ed782a2 commit c820eef
Show file tree
Hide file tree
Showing 5 changed files with 104 additions and 1,050 deletions.
28 changes: 28 additions & 0 deletions ISSUE_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
### Sample

<!-- Provide a link to the sample there’s an issue with e.g. https://github.com/xamarin/mobile-samples/tree/master/TaskyPro/ -->

### Description

<!-- Describe what the issue is -->

### Steps to Reproduce

1.
2.
3.

### Expected Behavior


### Actual Behavior


### Information

- IDE and IDE version: <!-- Visual Studio 2017 v15.6 / Visual Studio Mac v7.4 -->
- Platform with the issue: <!-- All that apply -->
- iOS: <!-- The version of the iOS SDK you are compiling against, e.g. 11.1 -->
- Android: <!-- The version of the Android SDK you are compiling against, e.g. 8.0 -->
- UWP: <!-- The version of the UWP SDK you are compiling against, e.g. 16299 -->
- Device or simulator/emulator: <!-- State whether the problem occurs on a device or a simulator/emulator -->
13 changes: 13 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
Copyright 2011 Xamarin Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
20 changes: 20 additions & 0 deletions PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
### Description of Change

<!-- Describe your changes here -->

<!-- Notes:
Do not update the Xamarin.Forms NuGet packages, or Android support libraries.
Do not use pre-release versions of NuGet packages.
If you update a NuGet package in a project, please ensure that you update the same package in the other projects in the sample (if present).
If you change code in the library project in a sample, please ensure that you thoroughly test the changes on all platforms.
If you change code in a platform project in a sample, please ensure that you thoroughly test the change on the platform.
-->

### Pull Request Checklist

<!-- Please complete -->

- [ ] Rebased on top of master at time of the pull request.
- [ ] Changes adhere to coding standard in the sample.
- [ ] Consolidated NuGet packages across all projects in the sample (when changing existing package versions).
- [ ] Tested changes on the appropriate platforms (all platforms if changing the library code).
122 changes: 43 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,124 +6,88 @@ This repository contains a number of samples that show how to share code between
License
-------

The Apache License 2.0 applies to all samples in this repository.
See the [license file](LICENSE) and any additional license information attached to each sample.

Copyright 2011 Xamarin Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Contributing
------------

Before adding a sample to the repository, please run either install-hook.bat
or install-hook.sh depending on whether you're on Windows or a POSIX system.
This will install a Git hook that runs the Xamarin code sample validator before
a commit, to ensure that all samples are good to go.

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

## Galleries
This repository welcomes contributions and suggestions. If you want to create a new sample, you need to work with an employee to help bring the new sample into the repository. Start by raising a [GitHub issue](https://github.com/xamarin/mobile-samples/issues/new) in this repository that outlines your proposed sample. Please note that samples in the MASTER branch of this repository shouldn't rely on preview or pre-release NuGet packages.

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 two sample galleries here:
The Xamarin [sample gallery](https://developer.xamarin.com/samples/) is powered by this repository, and therefore each sample needs to comply with the following requirements:

* [Xamarin Forms Samples](http://developer.xamarin.com/samples/xamarin-forms/all/)
* **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 [TaskyPro](https://github.com/xamarin/mobile-samples/tree/master/TaskyPro/Screenshots).

* [iOS Samples](http://developer.xamarin.com/samples/ios/all/)
* **Readme** - a `README.md` file that has the name of the sample, a description, and author attribution. For an example of this, see [TaskyPro](https://github.com/xamarin/mobile-samples/blob/master/TaskyPro/README.md).

* [Mac Samples](http://developer.xamarin.com/samples/mac/all/)
* **Metadata** - a `Metadata.xml` file that has the following information:

* [Android Samples](http://developer.xamarin.com/samples/android/all/)
* **ID** - a GUID for the sample.

## Sample GitHub Repositories
* **IsFullApplication** - a boolean value that indicates whether the sample is a full app, which could be submitted to an app store, or a feature sample.

These sample galleries are populated by samples in our six sample GitHub repos:
* **Brief** - a short description of what the sample does.

* [https://github.com/xamarin/xamarin-forms-samples](https://github.com/xamarin/xamarin-forms-samples)
* **Level** - the intended audience level for the sample: Beginner, Intermediate, or Advanced. Only the getting started samples are Beginner, 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.

* [https://github.com/xamarin/mobile-samples](https://github.com/xamarin/mobile-samples)
* **Minimum License Requirement** - Starter, Indie, Business, or Enterprise: denotes the license that a user has to have in order to build and run the sample.

* [https://github.com/xamarin/monotouch-samples](https://github.com/xamarin/monotouch-samples)
* **Tags**: a list of relevant tags for the app. See other metadata files for examples.

* [https://github.com/xamarin/mac-samples](https://github.com/xamarin/mac-samples)
* **SupportedPlatforms**: a comma-separated list of the supported platforms. Valid values are currently iOS, Android, and Windows.

* [https://github.com/xamarin/monodroid-samples](https://github.com/xamarin/monodroid-samples)
* **Gallery**: a boolean value that indicates whether the sample should appear in the Xamarin.Forms [sample gallery](https://developer.xamarin.com/samples/xamarin-forms/).

* [https://github.com/xamarin/mac-ios-samples](https://github.com/xamarin/mac-ios-samples)
For an example of a `Metadata.xml` file, see [TaskyPro](https://github.com/xamarin/mobile-samples/blob/master/TaskyPro/Metadata.xml).

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.
* **Buildable solution and .csproj file** - the project _must_ build and have the appropriate project scaffolding (solution + .csproj).

## Sample Requirements
This approach ensures that all samples integrate with the Xamarin [sample gallery](https://developer.xamarin.com/samples/).

We welcome sample submissions. Please ping Nat or Miguel for repo commit access.
If you have any questions, don't hesitate to ask on the [Xamarin Forums](https://forums.xamarin.com/).

However, because the sample galleries are powered by the github sample repos, each sample needs to have the following things:
## GitHub Integration

* **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.
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.

* **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)
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.

* **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:
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.

* **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
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).

* **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.
If you have any questions, don't hesitate to ask!

* **Brief** - Short description or what your sample does. This allows us to display a nice and clean vignette on the sample page.

* **Level** - Beginner, Intermediate, or Advanced: this is the intended audience level for the sample. only the getting started samples are Beginner, 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.

* **Minimum License Requirement** - Starter, Indie, Business, or Enterprise: denotes the license that a user has to have in order to build/run the sample.
# Other samples

* **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**
## Galleries

* **SupportedPlatforms**: this is only for cross plat samples. It's a comma-separated list, and the valid values are iOS, Android, and Windows.
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 two sample galleries here:

* **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.
* [Xamarin.Forms Samples](http://developer.xamarin.com/samples/xamarin-forms/all/)

* **Buildable Sln and CSProj file** - the project _must_ build and have the appropriate project scaffolding (solution + proj).
* [iOS Samples](http://developer.xamarin.com/samples/ios/all/)

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)
* [Mac Samples](http://developer.xamarin.com/samples/mac/all/)

For a x-platform sample, please see: https://github.com/xamarin/mobile-samples/tree/master/Tasky
* [Android Samples](http://developer.xamarin.com/samples/android/all/)

## GitHub Integration
## Sample GitHub Repositories

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.
These sample galleries are populated by samples in our six sample GitHub repos:

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.
* [https://github.com/xamarin/xamarin-forms-samples](https://github.com/xamarin/xamarin-forms-samples)

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.
* [https://github.com/xamarin/mobile-samples](https://github.com/xamarin/mobile-samples)

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).
* [https://github.com/xamarin/monotouch-samples](https://github.com/xamarin/monotouch-samples)

If you have any questions, don't hesitate to ask!
* [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/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.
Loading

0 comments on commit c820eef

Please sign in to comment.