Merge lp:~mvo/snapcraft/docs-1 into lp:~snappy-dev/snapcraft/core

[Michael Vogt]

Start working on the docs:

  - rename README.md to HACKING.md as its about snapcraft hacking
  - add new README.md that points to the docs under doc/
  - add docs/intro.md that explains some of the key concepts
  - add stub docs/tutorial.md

[lp:~mvo/snapcraft/docs-1]

107. By Michael Vogt on 2015-07-24

expand why we need parts at all

[Leo Arias (elopio)]

Some small typos, but this is great and clear. Thank you!

review: Needs Fixing

[Michael Terry (mterry)]

A few comments too. Thanks for this work, mvo!

[Daniel Holbach (dholbach)]

Great work. After Mike's review there was only one more comment to leave. :-)

[Michael Terry (mterry)]

mvo is on vacation for two weeks, I'll take this branch over in a new MP.

[Michael Terry (mterry)]

Moved to https://code.launchpad.net/~snappy-dev/snapcraft/docs/+merge/266243

review: Disapprove

Unmerged revisions

=== renamed file 'README.md' => 'HACKING.md'
=== added file 'README.md'
--- README.md	1970-01-01 00:00:00 +0000
+++ README.md	2015-07-24 07:39:58 +0000
@@ -0,0 +1,7 @@
+# Snapcraft
+
+Snapcraft allows easy crafting of snap packages for the Ubuntu Core
+transactional system.
+
+See docs/intro.md for details about the concepts behind
+snapcraft. There is also a tutorial in docs/tutorial.md.
\ No newline at end of file

=== added file 'docs/intro.md'
--- docs/intro.md	1970-01-01 00:00:00 +0000
+++ docs/intro.md	2015-07-24 07:39:58 +0000
@@ -0,0 +1,71 @@
+# Into
+
+Snapcraft allows easy crafting of snap packages for the Ubuntu Core
+transactional system. It is designed to make it easy to incorporate
+components from different sources like github, launchpad or npm.
+
+# Key concepts
+
+A .snap package for the Ubuntu Core system contains all its
+dependencies. This has a couple of advantages over traditional deb or
+rpm based dependency handling, the most important one is that a
+developer can always be assured that there no regressions triggered by
+changes of the system.
+
+Snapcraft makes bundling these dependencies easy by allowing to
+specify them as "parts" in the snapcraft.yaml file.
+
+## Parts
+
+A central aspect of a snapcraft recipe is a "part". A part is a piece
+of software or data that the snap package requires to work or to
+build other parts. Each part is managed by a snapcraft plugin and parts
+are independent of each other.
+
+## Plugins
+
+Snapcraft plugins are written in python and have a yaml
+description. This allows to easily extend snapcraft with custom
+plugins. A lot of default plugins are included, for example for
+projects written in go, java, python or autotools. It is also possible
+to simply download content as part of the snapcraft recipe.
+
+## Lifecycle
+
+Each part goes through the following steps:
+
+### Pull
+
+The first is that each part is pulled. This step will download
+content, e.g. checkout a git repository or download a binary component
+like the java sdk. Snapcraft will create a parts/ directory with
+sub-directories like parts/part-name/src for each part that contains
+the downloaded content.
+
+#### Build
+
+The next step is that each part is build in its parts/part-name/build
+directory and installs itself into parts/part-name/install.
+
+### Stage
+
+After the build of each part the parts are combined into a single
+directory tree that is called the "staging area". It can be found
+under the ./stage directory.
+
+### Snap
+
+The snap step move the data into a ./snap directory. It contains only
+the content that will be put into the final snap package.
+
+### Assemble
+
+The final step builds a snap package out of the snap directory.
+
+More details on the flow can be found in the docs/flow.md document.
+
+# Next
+
+After introducing the key concept of snapcraft it is probably a good
+time to look at the tutorial in docs/tutorial.md to see how it works
+for an example project.
\ No newline at end of file

=== added file 'docs/tutorial.md'
--- docs/tutorial.md	1970-01-01 00:00:00 +0000
+++ docs/tutorial.md	2015-07-24 07:39:58 +0000
@@ -0,0 +1,3 @@
+# Snapcraft tutorial
+
+This tutorial walks through making a snap for a XXX application.
\ No newline at end of file