Merge pull request #188 from markshuttle/patch-1

Small text cleanups for README and charmcraft help

CODE_OF_CONDUCT.md

@@ -4,10 +4,11 @@
 
 In the interest of fostering an open and welcoming environment, we as
 contributors and maintainers pledge to make participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
+our community a harassment-free experience for everyone, regardless of age,
+body size, disability, ethnicity, sex characteristics, gender identity and
+expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
 
 ## Our Standards
 
@@ -23,25 +24,25 @@ include:
 Examples of unacceptable behavior by participants include:
 
 * The use of sexualized language or imagery and unwelcome sexual attention or
- advances
+  advances
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or electronic
- address, without explicit permission
+  address, without explicit permission
 * Other conduct which could reasonably be considered inappropriate in a
- professional setting
+  professional setting
 
 ## Our Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+Project maintainers are responsible for clarifying the standards of
+acceptable behavior and are expected to take appropriate and fair corrective
+action in response to any instances of unacceptable behavior.
 
 Project maintainers have the right and responsibility to remove, edit, or
 reject comments, commits, code, wiki edits, issues, and other contributions
 that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
+permanently any contributor for other behaviors that they deem
+inappropriate, threatening, offensive, or harmful.
 
 ## Scope
 
@@ -55,22 +56,25 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior
-may be reported by contacting the project team at
-[email protected]. All complaints will be reviewed and
-investigated and will result in a response that is deemed necessary
-and appropriate to the circumstances. The project team is obligated to
-maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted
-separately.
+may be reported by contacting the project team at:
+
+`[email protected]`
+
+All complaints will be reviewed and investigated and will result in a
+response that is deemed necessary and appropriate to the circumstances. The
+project team is obligated to maintain confidentiality with regard to the
+reporter of an incident.  Further details of specific enforcement policies
+may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other
 members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 
 [homepage]: https://www.contributor-covenant.org
 

HOWTO_RELEASE.md

@@ -2,9 +2,9 @@
 
 Release early, release often. Don't be lazy.
 
-To use this doc: just replace X.Y.Z with the major.minor.patch version 
-of the release, and all commands and indications should be ready 
-to copy and paste,.
+To use this doc: just replace X.Y.Z with the major.minor.patch version of
+the release. The sequence of commands below should be good to copy and
+paste, but do please pay attention to details!
 
 
 ## Preparation
@@ -21,7 +21,7 @@ to copy and paste,.
 
     git checkout -b release-X.Y.Z
 
-- create release notes after all main changes from last tag 
+- create release notes after all main changes from last tag
 
     git log --first-parent master --decorate
 
@@ -66,10 +66,13 @@ to copy and paste,.
 - release in Github
 
     xdg-open https://github.com/canonical/charmcraft/tags
-    (you should see all project tags, the top one should be this release's one)
-    In the menu at right of the tag tag you just created, choose 'create release'
-    Copy the release notes into the release description
+
+    You should see all project tags, the top one should be this release.
+    In the menu at right of the tag tag you just created, choose 'create
+    release'. Copy the release notes into the release description.
+
     Attach the `dist/` files
+
     Click on "Publish release"
 
 - release to PyPI
@@ -86,16 +89,16 @@ to copy and paste,.
 
 - verify all archs are consistent:
 
-    snapcraft status charmcraft 
+    snapcraft status charmcraft
 
 
 ## Final details
 
 - update IRC channel topic
 
-- send a mail with "Release X.Y.Z" title and release notes in the body to 
+- send a mail with "Release X.Y.Z" title and release notes in the body to
 
-    [email protected] 
+    [email protected]
 
 - write a new post in Discourse about the release:
 

README.md

@@ -1,60 +1,145 @@
-# What is charmcraft?
+# Charmcraft is for Kubernetes operator developers
+
+Charmcraft supports Kubernetes operator development.
+
+Charmcraft enables collaboration between operator developers, and
+publication on [Charmhub](https://charmhub.io/), home of the Open Operator
+Collection.
 
-Charmcraft provides a streamlined, powerful, opinionated, and flexible tool to
-develop, package, and manage the lifecycle of Juju charm publication, focused
-particularly on charms written within the [Operator Framework].
+Use `charmcraft` to:
 
-[Operator Framework]: https://pypi.org/project/ops/
+ * Init a new charm file structure
+ * Build your operator into a charm for distribution
+ * Register your charm name on Charmhub
+ * Upload your charms to Charmhub
+ * Release your charms into channels
 
-It is still in heavy, initial development and so a lot is still To Be
-Done. However it is already useful, and already simplifies the life of the
-charmer.
+You can use charmcraft with operators written in any language but we
+recommend the [Python Operator Framework on
+Github](https://github.com/canonical/operator) which is also [on
+PyPI](https://pypi.org/project/ops/) for ease of development and
+collaboration.
 
-## How do I install it?
+Charmcraft and the Python Operator Framework extend the operator pattern
+beyond Kubernetes with [universal
+operators](https://juju.is/universal-operators) that drive Linux and
+Windows apps. The universal operator pattern is very exciting for
+multi-cloud application management.
 
-The easiest way to install `charmcraft` is by doing
+## Install
 
-    sudo snap install --beta charmcraft
+The easiest way to install `charmcraft` is with
+
+    sudo snap install charmcraft --beta
+
+There are multiple channels other than `--beta`. See the full list with
+`snap info charmcraft`. We recommend either `latest/stable` or `latest/beta`
+for everyday charming. With the snap you will always be up to date as
+Charmhub services and APIs evolve.
 
-(more options are available as per `snap info charmcraft`) but some
-people with more esoteric needs not covered by the snap might need to
-instead go via `pip3 install --user charmcraft`.
+You can also install from PyPI with `pip3 install --user charmcraft`
 
-## What can it do for me today?
+## Initialize a charm operator package file structure
 
-It can build your charm! No need for git submodules nor pesky hook symlinks, you
-can concentrate on your charm being pure python code (plus the required juju
-metadata), and `charmcraft` will fill in the boring bits for you.
+Use `charmcraft init` to create a new template charm operator file tree:
 
-For example, given a charm that consists exclusively of
+```bash
+$ mkdir my-new-charm; cd my-new-charm
+$ charmcraft init
+All done.
+There are some notes about things we think you should do.
+These are marked with ‘TODO:’, as is customary. Namely:
+      README.md: fill out the description
+      README.md: explain how to use the charm
+  metadata.yaml: fill out the charm's description
+  metadata.yaml: fill out the charm's summary
+```
 
-    my-charm
-    ├── metadata.yaml
-    ├── requirements.txt
-    └── src/
-        └── charm.py
+You will now have all the essential files for a charmed operator, including
+the actual `src/charm.py` skeleton and various items of metadata. Charmcraft
+assumes you want to work in Python so it will add `requirements.txt` with
+the Python operator framework `ops`, and other conventional development
+support files.
 
-(and assuming `ops` is in `requirements.txt`), then running `charmcraft build`
-will produce a charm that looks like
+## Build your charm
 
-    my-charm
-    ├── dispatch
-    ├── hooks
-    │   ├── install -> ../dispatch
-    │   ├── start -> ../dispatch
-    │   └── upgrade-charm -> ../dispatch
-    ├── metadata.yaml
-    ├── src/
-    │   └── charm.py
-    └── venv/
-        ├── ops/
-        │   ├── ...
-        └── yaml/
-            └── ...
+With a correct `metadata.yaml` and with `ops` in `requirements.txt` you can
+build a charm with:
 
-which should be all you need to `juju deploy` the charm!
+```text
+$ charmcraft build
+Created 'test-charm.charm'.
+```
 
-## How do I run it from source?
+`charmcraft build` will fetch additional files into the tree from PyPI based
+on `requirements.txt` and will compile modules using a virtualenv.
+
+The charm is just a zipfile with metadata and the operator code itself:
+
+```text
+$ unzip -l test-charm.charm
+Archive:  test-charm.charm
+  Length      Date    Time    Name
+---------  ---------- -----   ----
+      221  2020-11-15 08:10   metadata.yaml
+[...]
+    25304  2020-11-15 08:14   venv/yaml/__pycache__/scanner.cpython-38.pyc
+---------                     -------
+   812617                     84 files
+```
+
+Now, if you have a Kubernetes cluster with the Juju OLM accessible you can
+directly `juju deploy <test-charm.charm>` to the cluster. You do not need to
+publish your operator on Charmhub, you can pass the charm file around
+directly to users, or for CI/CD purposes.
+
+## Charmhub login and charm name reservations
+
+[Charmhub](https://charmhub.io/) is the world's largest repository of
+operators.  It makes it easy to share and collaborate on operators. The
+community are interested in operators for a very wide range of purposes,
+including infrastructure-as-code and legacy application management, and of
+course Kubernetes operators.
+
+Use `charmcraft login` and `charmcraft logout` to sign into Charmhub.
+
+## Charmhub name registration
+
+You can register operator names in Charmhub with `charmcraft register
+<name>`. Many common names have been reserved, you are encouraged to discuss
+your interest in leading or collaborating on a charm in [Charmhub
+Discourse](https://discourse.charmhub.io/).
+
+Charmhub naming policy is the principle of least surprise - a well-known
+name should map to an operator that most people would expect to get for that
+name.
+
+Operators in Charmhub can be renamed as needed, so feel free to register a
+temporary name, such as <username>-<charmname> as a placeholder.
+
+## Operator upload and release
+
+Charmhub operators are published in channels, like:
+
+```text
+latest/stable
+latest/candidate
+latest/beta
+latest/edge
+1.3/beta
+1.3/edge
+1.2/stable
+1.2/candidate
+1.0/stable
+```
+
+Use `charmcraft upload` to get a new revision number for your freshly built
+charm, and `charmcraft release` to release a revision into any particular
+channel for your users.
+
+# Charmcraft source
+
+Get the source from github with:
 
     git clone https://github.com/canonical/charmcraft.git
     cd charmcraft
@@ -67,3 +152,5 @@ If you would like to run the tests you can do so with
 
     pip install -r requirements-dev.txt
     ./run_tests
+
+Contributions welcome!

charmcraft/commands/build.py

@@ -110,7 +110,7 @@ def run(self):
         self.handle_dependencies()
         zipname = self.handle_package()
 
-        logger.info("Done, charm left in '%s'", zipname)
+        logger.info("Created '%s'.", zipname)
         return zipname
 
     def _load_juju_ignore(self):
@@ -352,34 +352,40 @@ def validate_requirement(self, filepaths):
 
 
 _overview = """
-Build the charm, leaving a .charm file as the result of the process.
+Build a charm operator package.
 
-You can `juju deploy` directly from the resulting .charm file, or upload it to
-the store (see the "upload" command).
+You can `juju deploy` the resulting `.charm` file directly, or upload it
+to Charmhub with `charmcraft upload`.
+
+You must be inside a charm directory with a valid `metadata.yaml`,
+`requirements.txt` including the `ops` package for the Python operator
+framework, and an operator entrypoint, usually `src/charm.py`.
+
+See `charmcraft init` to create a template charm directory structure.
 """
 
 
 class BuildCommand(BaseCommand):
     """Build the charm."""
     name = 'build'
-    help_msg = "Build the charm."
+    help_msg = "Build the charm"
     overview = _overview
     common = True
 
     def fill_parser(self, parser):
         """Add own parameters to the general parser."""
         parser.add_argument(
             '-f', '--from', type=pathlib.Path,
-            help="The directory where the charm project is located, where the build "
-                 "is done from; defaults to '.'.")
+            help="Charm directory with metadata.yaml where the build "
+                 "takes place; defaults to '.'")
         parser.add_argument(
             '-e', '--entrypoint', type=pathlib.Path,
-            help="The executable script or program which is the entry point to all the "
-                 "charm code; defaults to 'src/charm.py'.")
+            help="The executable which is the operator entry point; "
+                 "defaults to 'src/charm.py'")
         parser.add_argument(
             '-r', '--requirement', action='append', type=pathlib.Path,
-            help="The file(s) with the needed dependencies (this option can be used multiple "
-                  "times); defaults to 'requirements.txt'.")
+            help="File(s) listing needed PyPI dependencies (can be used multiple "
+                  "times); defaults to 'requirements.txt'")
 
     def run(self, parsed_args):
         """Run the command."""