drafting an introduction document to how releases work

docs/git-database.md

@@ -0,0 +1,26 @@
+# Working with the Git Database
+
+### Tag a Commit
+
+Tags can be created through the GitHub API
+
+```
+var tag = new NewTag {
+    Message = "Tagging a new release of Octokit",
+    Tag = "v1.0.0",
+    Object = "ee062e0", // short SHA
+    Type = TaggedType.Commit, // TODO: what are the defaults when nothing specified?
+    Tagger = new Signature
+    {
+        Name = "Brendan Forster",
+        Email = "brendan@github.com",
+        Date = DateTime.UtcNow
+    }	
+};
+var result = await client.GitDatabase.Tags.Create("octokit", "octokit.net", tag);
+Console.WriteLine("Created a tag for {0} at {1}", result.Tag, result.Sha);
+```
+
+Or you can fetch an existing tag from the API:
+
+var tag = await client.GitDatabase.Tags.Get("octokit", "octokit.net", "v1.0.0");

docs/releases.md

@@ -0,0 +1,62 @@
+# Working with Releases
+
+### Get All
+
+To retrieve all releases for a repository:
+
+```
+var releases = client.Release.GetAll("octokit", "octokit.net");
+var latest = releases[0];
+Console.WriteLine(
+    "The latest release is tagged at {0} and is named {1}", 
+    latest.TagName, 
+    latest.Name);
+```
+
+### Create
+
+To create a new release you must have a corresponding tag in the repository. See the `git-database.md` docs for details.
+
+```
+var newRelease = new ReleaseUpdate("v1.0.0");
+newRelease.Name = "Version One Point Oh";
+newRelease.Body = "**This** is some *Markdown*";
+newRelease.Draft = true;
+newRelease.PreRelease = false;
+
+var result = await client.Release.Create("octokit", "octokit.net", newRelease);
+Console.WriteLine("Created release id {0}", release.Id);
+```
+
+Note that the `Draft` flag is used to indicate when a release should be published to the world, whereas the `PreRelease` flag is used to indicate whether a release is unofficial or preview release.
+
+### Update
+
+Once the release is ready for the public, you can apply an update to the release:
+
+```
+var release = client.Release.Get("octokit", "octokit.net", 1);
+var updateRelease = release.ToUpdate();
+updateRelease.Draft = false;
+updatedRelease.Name = "Version 1.0";
+updatedRelease.TargetCommitish = "0edef870ecd885cc6506f1e3f08341e8b87370f2" // can also be a ref
+var result = await client.Release.Edit("octokit", "octokit.net", 1, updateRelease);
+```
+
+### Upload Assets
+
+If you have any assets to include with the release, you can upload them after creating the release:
+
+```
+var archiveContents = await File.ReadAllBytes("output.zip"); // TODO: better sample
+var assetUpload = new ReleaseAssetUpload() 
+{
+     FileName = "my-cool-project-1.0.zip",
+     Content-Type = "application/zip",
+     RawData = archiveContents
+};
+var release = client.Release.Get("octokit", "octokit.net", 1);
+var asset = await client.Release.UploadAsset(release, assetUpload);
+```
+
+**TODO:** are there any known limits documented to upload assets?