puppet-strings 0.4.0 → 0.99.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c5d45a8489fb4754aebb00abe3afb2e85b4e75c
-  data.tar.gz: cb074d7c812e50b1a1ffbbe42cafde1a909fb125
+  metadata.gz: a6a68c372004eb1cf650ae8542c16dd019614ec1
+  data.tar.gz: b4e29585c10fa54c4ad5a141a0c04ac22f642739
 SHA512:
-  metadata.gz: 5bc48f92940b474aeddff28cad23338216db262815dec6abfc275aaf39f7c458a9d2a4d160c5131898724310e4ef75fe657f597164b80ede62fd9066d616ec9e
-  data.tar.gz: 9ce5ee6be34c1727855f9c1f99bb2049146b3434ab4bc5b51579d698cd15e531b70ae3a466beb77b08599ff0439cbf6c2e077c4556cb3d01448e5dd5adaf0a20
+  metadata.gz: 8e2d046b43f397bd7f6580e7312edb4f1a7e58de320927af653bcf2c0f830b4260a0473616c8817f98561cf38ea997951ebe96b1697e4507a3041546168a9d28
+  data.tar.gz: c5828dc16270f1e2a51f77ff2be199c322b2c5d7e95eb72178bf9151998b0e804ac1efde40e22c279f3541b1e3fb50c11fa7b2c43c2bbcd54c07169f4cf71385

data/CHANGELOG.md

@@ -0,0 +1,122 @@
+##2016-10-10 - Release 0.99.0
+
+###Summary
+
+This release includes a complete rewrite of strings, fixing many bugs from previous versions and generally improving the user experience. This release is intended to be the last stop before the strings major version 1.0 is released, and nearly all of the functionality of the major release is included.
+
+All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.99.0](https://tickets.puppetlabs.com/issues/?filter=22705).
+
+###Features
+- Complete overhaul, including code cleanup, bug fixes and new functionality **(PDOC-63)**
+  - Documentation has been split into sections based on type: puppet 3x API functions, puppet 4x API functions, ruby classes, puppet language functions, types, and providers
+  - New JSON schema organized to reflect the separation of types
+  - Support for custom functions written in the puppet language
+  - Support for puppet function overloads via the create_function 4.x API
+  - YARD bumped to latest version, 0.9.5
+- Markdown is now the default format for parsing docstring text **(PDOC-86)**
+  - Note: this means Markdown text in YARD comments and tags, not a change in the output of strings
+- New commandline options: --emit-json and --emit-json-stdout to generate JSON documentation **(PDOC-84)**
+- Runtime dependency on Puppet has been removed, allowing strings to function in Puppet Enterprise 3.8 **(PDOC-80)**
+  - Note that the gem still requires puppet. We recommend that the strings gem be installed with puppet, as suggested in the  [README](https://github.com/puppetlabs/puppet-strings/blob/master/README.md#installing-puppet-strings)
+- New gemspec requirement on Ruby version 1.9.3, the oldest supported Ruby version
+
+###BugFixes
+
+- Prevents a blizzard of errors when documenting Puppet Core source and some puppet modules **(PDOC-63)**
+  - As this is a complete rewrite, many known and unknown bugs from the original code were fixed along the way
+- Allow strings to be installed in PE 3.8 without overwriting existing puppet and facter installations with newer gems
+
+##2016-03-30 - Release 0.4.0
+
+###Summary
+
+This release adds JSON output support for strings, fixes a major bug that prevented strings from working with the 4.4.0 release of puppet, and is the last version of strings that will be released as a module.
+
+All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.4.0](https://tickets.puppetlabs.com/issues/?filter=18810).
+
+###Features
+- Support for JSON output **(PDOC-23)**
+  - Strings now has the ability to produce a JSON representation of a given puppet module
+  - The details of the JSON schema can be found [here](https://github.com/puppetlabs/puppet-strings/blob/master/json_dom.md)
+  - For details on how to generate JSON, see the [README](https://github.com/puppetlabs/puppet-strings/blob/master/README.md#running-puppet-strings)
+- Migrate to ruby gems as a distribution method **(PDOC-28)**
+  - This is the last release of strings that will be available as a puppet module
+  - The 0.4.0 release will be released concurrently as a ruby gem
+  - After this release, all updates will only be available via the gem
+
+###Bugfixes
+
+- Fix issue that prevented strings from running with Puppet 4.4.0 **(PDOC-75)**
+
+##2015-09-22 - Release 0.3.1
+
+###Summary
+
+This is a minor bug fix release.
+
+All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.3.1](https://tickets.puppetlabs.com/issues/?filter=15530).
+
+###Bugfixes
+
+- Prevent strings from printing unnecessary quotes in error messages **(PDOC-57)**
+- Issue correct type check warnings for defined types **(PDOC-56)**
+- Allow providers, types, and defines to have the same name **(PDOC-54)**
+
+##2015-09-21 - Release 0.3.0
+
+###Summary
+
+This release includes support for Puppet Types and Providers, as well as
+type checking Puppet 4x functions and defined types.
+
+All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with
+the fix version of [0.3.0](https://tickets.puppetlabs.com/issues/?filter=15529).
+
+####Features
+
+- Support for Puppet Types and Providers **(PDOC-35)**
+- Type check Puppet 4x functions and defined types where possible and warn the user when types don't match.
+  - Type check defined types **(PDOC-21)**
+  - Type check Puppet 4x functions **(PDOC-38)** **(PDOC-19)** **(PDOC-37)**
+  - Output type info in generated HTML **(PDOC-19)**
+- Improved warnings and logging.
+  - Create a consistent style for warnings. **(PDOC-49)**
+  - All warnings get printed on stderr.
+  - Yard warnings are redirected to a log file **(PDOC-38)**
+  - Prevent duplicate warnings **(PDOC-38)**
+- Improved README installation and usage instructions.
+  - Installation instructions using Puppet **(PDOC-33)**
+
+
+####Bugfixes
+
+- Fix markdown list processing **(PDOC-30)**
+- Fix namespacing for nested classes and defined types **(PDOC-20)**
+
+
+##2015-03-17 - Release 0.2.0
+
+###Summary
+
+This release includes improvements to the HTML output generated by strings and a few bug fixes.
+All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.2.0](https://tickets.puppetlabs.com/issues/?filter=13760).
+
+[PDOC JIRA]: https://tickets.puppetlabs.com/browse/PDOC
+
+####Features
+- Custom YARD templates for classes and defined types **(PDOC-17)**
+    - Improved HMTL output that is more appropriate for Puppet code (especially for parameters)
+    - Support for the explicit list of YARD tags we will be supporting initially (@param, @return, @since, @example)
+    - Our own custom YARD templates which can be easily extended and tweaked
+
+- Custom YARD templates for 3.x and 4.x functions **(PDOC-24)**
+    - Improved HMTL output that is more appropriate for listing several functions on one webpage in addition to being more consistent with the HTML produced for classes and defined types.
+    - Support for the explicit list of YARD tags we will be supporting initially (@param, @return, @since, @example)
+    - Our own custom YARD templates which can be easily extended and tweaked
+- Addition of RubCop Travis CI job to ensure code quality and consistency **(PDOC-8)**
+
+####Bugfixes
+- Puppet namespaces are no longer mangled for nested classes and defined types **(PDOC-25)**
+- Strings is now compatible with the renaming of the Puppetx/puppetx namespace to PuppetX/puppet_x **(PDOC-26)**
+- Strings will no longer crash when documenting 3x functions with less than two arguments passed into newfunction **(PDOC-27)**
+

data/COMMITTERS.md

@@ -0,0 +1,185 @@
+Committing changes to Strings
+====
+
+We would like to make it easier for community members to contribute to strings
+using pull requests, even if it makes the task of reviewing and committing
+these changes a little harder.  Pull requests are only ever based on a single
+branch. As a result contributors should target their changes at the master branch.
+This makes the process of contributing a little easier for the contributor since 
+they don't need to concern themselves with the question, "What branch do I base my changes
+on?"  This is already called out in the [CONTRIBUTING.md](http://goo.gl/XRH2J).
+
+Therefore, it is the responsibility of the committer to re-base the change set
+on the appropriate branch which should receive the contribution.
+
+It is also the responsibility of the committer to review the change set in an
+effort to make sure the end users must opt-in to new behavior that is
+incompatible with previous behavior.  We employ the use of [feature
+flags](http://stackoverflow.com/questions/7707383/what-is-a-feature-flag) as
+the primary way to achieve this user opt-in behavior.  Finally, it is the
+responsibility of the committer to make sure the `master` branch
+is clean and working at all times.  Clean means that dead code is not
+allowed, everything needs to be usable in some manner at all points in time.
+
+The rest of this document addresses the concerns of the committer.  This
+document will help guide the committer decide which branch to base, or re-base
+a contribution on top of.  This document also describes our branch management
+strategy, which is closely related to the decision of what branch to commit
+changes into.
+
+Terminology
+====
+
+Many of these terms have more than one meaning.  For the purposes of this
+document, the following terms refer to specific things.
+
+**contributor** - A person who makes a change to strings and submits a change
+set in the form of a pull request.
+
+**change set** - A set of discrete patches which combined together form a
+contribution.  A change set takes the form of Git commits and is submitted to
+strings in the form of a pull request.
+
+**committer** - A person responsible for reviewing a pull request and then
+making the decision what base branch to merge the change set into.
+
+**base branch** - A branch in Git that contains an active history of changes
+and will eventually be released using semantic version guidelines.  The branch
+named `master` will always exist as a base branch.
+
+**master branch** - The branch where new functionality that and bug fixes are
+merged.
+
+**security** - Where critical security fixes are merged.  These change sets
+will then be merged into release branches independently from one another. (i.e.
+no merging up).  Please do not submit pull requests against the security branch
+and instead report all security related issues to security@puppet.com as
+per our security policy published at
+[https://puppet.com/security/](https://puppet.com/security/).
+
+Committer Guide
+====
+
+This section provides a guide to follow while committing change sets to strings
+base branches.
+
+How to decide what release(s) should be patched
+---
+
+This section provides a guide to help a committer decide the specific base
+branch that a change set should be merged into.
+
+The latest minor release of a major release is the only base branch that should
+be patched.  These patches will be merged into `master` if they contain new
+functionality and  if they fix a critical bug.  Older minor releases in a major release 
+do not get patched.
+
+Before the switch to [semantic versions](http://semver.org/) committers did not
+have to think about the difference between minor and major releases.
+Committing to the latest minor release of a major release is a policy intended
+to limit the number of active base branches that must be managed.
+
+Security patches are handled as a special case.  Security patches may be
+applied to earlier minor releases of a major release, but the patches should
+first be merged into the `security` branch.  Security patches should be merged
+by Puppet Labs staff members.  Pull requests should not be submitted with the
+security branch as the base branch.  Please send all security related
+information or patches to security@puppet.com as per our [Security
+Policy](https://puppet.com/security/).
+
+The CI systems are configured to run against `master`.  Over time, this branch 
+will refer to different versions, but its name will remain fixed to avoid having 
+to update CI jobs and tasks as new versions are released.
+
+Code review checklist
+---
+
+This section aims to provide a checklist of things to look for when reviewing a
+pull request and determining if the change set should be merged into a base
+branch:
+
+ * All tests pass
+ * Are there any platform gotchas? (Does a change make an assumption about
+   platform specific behavior that is incompatible with other platforms?  e.g.
+   Windows paths vs. POSIX paths.)
+ * Is the change backwards compatible? (It should be)
+ * Are there YARD docs for API changes?
+ * Does the change set also require documentation changes? If so is the
+   documentation being kept up to date?
+ * Does the change set include clean code?  (software code that is formatted
+   correctly and in an organized manner so that another coder can easily read
+   or modify it.)  HINT: `git diff master --check`
+ * Does the change set conform to the contributing guide?
+
+Commit citizen guidelines:
+---
+
+This section aims to provide guidelines for being a good commit citizen by
+paying attention to our automated build tools.
+
+ * Don’t push on a broken build.  (A broken build is defined as a failing job
+   in [Puppet Strings](https://jenkins.puppetlabs.com/job/platform_puppet-strings_unit-ruby_master/)
+   page.)
+ * Watch the build until your changes have gone through green
+ * Update the ticket status and target version.  The target version field in
+   our issue tracker should be updated to be the next release of Puppet.  For
+   example, if the most recent release of Puppet is 3.1.1 and you merge a
+   backwards compatible change set into master, then the target version should
+   be 3.2.0 in the issue tracker.)
+ * Ensure the pull request is closed (Hint: amend your merge commit to contain
+   the string `closes #123` where 123 is the pull request number and github
+   will automatically close the pull request when the branch is pushed.)
+
+Example Procedure
+====
+
+This section helps a committer rebase and merge a contribution into the base branch.
+
+Suppose a contributor submits a pull request based on master.  The change set
+fixes a bug reported against strings 0.1.0  which is the most recently released
+version of strings.
+
+First, the committer pulls down the branch using the `hub` gem.  This tool
+automates the process of adding the remote repository and creating a local
+branch to track the remote branch.
+
+    $ hub checkout https://github.com/puppetlabs/puppet-strings/pull/123
+    Branch jeffmccune-pdoc-34_fix_foo_error set up to track remote branch pdoc-34-fix_foo_error from jeffmccune.
+    Switched to a new branch 'jeffmccune-pdoc-34_fix_foo_error'
+
+It's possible that more changes have been merged into master since the pull
+request was submitted. In this case it may be necessary to rebase the branch
+that contains the changes:
+
+    $ git rebase upstream/master
+
+After the branch has been checked out and rebased, the committer should ensure that
+the code review check list has been completed.
+
+Now that we have a topic branch containing the change set based on the most recent 
+`master` branch, the committer merges in:
+
+    $ git checkout master
+    Switched to branch 'master'
+    $ git merge --no-ff --log jeffmccune-pdoc-34_fix_foo_error
+    Merge made by the 'recursive' strategy.
+     foo | 0
+     1 file changed, 0 insertions(+), 0 deletions(-)
+     create mode 100644 foo
+
+Once the change set has been merged into one base branch, the change set should
+not be modified in order to keep the history clean, avoid "double" commits, and
+preserve the usefulness of `git branch --contains`.  If there are any merge
+conflicts, they are to be resolved in the merge commit itself and not by
+re-writing (rebasing) the patches for one base branch, but not another.
+
+Once the change set has been merged into `master`, the committer pushes.
+Please note, the checklist should be complete at this point. It's helpful to make
+sure your local branches are up to date to avoid one of the branches failing to fast
+forward while the other succeeds.
+
+    $ git push origin master:master
+
+That's it!  The committer then updates the pull request, updates the issue in
+our issue tracker, and keeps an eye on the [build
+status](http://jenkins.puppetlabs.com).

data/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# How to contribute
+
+Third-party patches are essential for keeping strings great. We want to keep it
+as easy as possible to contribute changes that get things working in your
+environment. There are a few guidelines that we need contributors to follow so
+that we can have a chance of keeping on top of things.
+
+## Getting Started
+
+* Make sure you have a [Jira account](http://tickets.puppetlabs.com)
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a ticket for your issue, assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+  * This is usually the master branch.
+  * Only target release branches if you are certain your fix must be on that
+    branch.
+  * To quickly create a topic branch based on master; `git checkout -b
+    fix/master/my_contribution master`. Please avoid working directly on the
+    `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+
+````
+    (PDOC-123) Make the example in CONTRIBUTING imperative and concrete
+
+    Without this patch applied the example commit message in the CONTRIBUTING
+    document is not a concrete example.  This is a problem because the
+    contributor is left to imagine what the commit message should look like
+    based on a description rather than an example.  This patch fixes the
+    problem by making the example concrete and imperative.
+
+    The first line is a real life imperative statement with a ticket number
+    from our issue tracker.  The body describes the behavior without the patch,
+    why this is a problem, and how the patch fixes the problem when applied.
+````
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Making Trivial Changes
+
+### Documentation
+
+For changes of a trivial nature to comments and documentation, it is not
+always necessary to create a new ticket in Jira. In this case, it is
+appropriate to start the first line of a commit with '(doc)' instead of
+a ticket number. 
+
+````
+    (doc) Add documentation commit example to CONTRIBUTING
+
+    There is no example for contributing a documentation commit
+    to the Puppet repository. This is a problem because the contributor
+    is left to assume how a commit of this nature may appear.
+
+    The first line is a real life imperative statement with '(doc)' in
+    place of what would have been the ticket number in a
+    non-documentation related commit. The body describes the nature of
+    the new documentation or comments added.
+````
+
+## Submitting Changes
+
+* Sign the [Contributor License Agreement](http://links.puppet.com/cla).
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the puppetlabs organization.
+* Update your Jira ticket to mark that you have submitted code and are ready for it to be reviewed (Status: Ready for Merge).
+  * Include a link to the pull request in the ticket.
+* The core team looks at Pull Requests on a regular basis in a weekly triage
+  meeting that we hold in a public Google Hangout. The hangout is announced in
+  the weekly status updates that are sent to the puppet-dev list.
+* After feedback has been given we expect responses within two weeks. After two
+  weeks will may close the pull request if it isn't showing any activity.
+
+# Additional Resources
+
+* [More information on contributing](http://links.puppet.com/contribute-to-puppet)
+* [Bug tracker (Jira)](http://tickets.puppetlabs.com)
+* [Contributor License Agreement](http://links.puppet.com/cla)
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
+* #puppet-dev IRC channel on freenode.org

data/Gemfile

@@ -0,0 +1,38 @@
+source ENV['GEM_SOURCE'] || "https://rubygems.org"
+
+gemspec
+
+gem 'rgen'
+gem 'redcarpet'
+gem 'yard', '~> 0.9.5'
+
+puppetversion = ENV['PUPPET_VERSION']
+
+if puppetversion
+  gem 'puppet', puppetversion
+else
+  gem 'puppet'
+end
+
+group :test do
+  gem "rspec", "~> 3.1"
+  gem 'mocha'
+  gem 'puppetlabs_spec_helper'
+  gem 'serverspec'
+  gem 'rubocop', '~> 0.41.0'
+end
+
+group :acceptance do
+  gem 'beaker', '< 3.0'
+  gem 'beaker-rspec'
+  gem 'beaker-hostgenerator'
+end
+
+group :development do
+  gem 'pry'
+  if RUBY_VERSION[0..2] == '1.9'
+    gem 'pry-debugger'
+  elsif RUBY_VERSION[0] == '2'
+    gem 'pry-byebug'
+  end
+end