Skip to content

Commit 3840851

Browse files
kpaulissekpaulisse
authored
Merge pull request #57 from github/kpaulisse-release-1-0
Release 1.0 branch
2 parents 65e4457 + 96d1ea8 commit 3840851

255 files changed

Lines changed: 6108 additions & 2042 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
0.6.1
1+
0.99.rc1

‎README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@ At GitHub, we manage thousands of nodes with a Puppet code base containing 500,0
88

99
`octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
1010

11-
It is under active development at this time. We suspect that with the initial release, some people who try it out could be using configurations of Puppet that we haven't experienced within our environment. We are eager to identify and fix as many of these as we can to expand the compatibility of this tool as much as possible.
11+
**The current version of `octocatalog-diff` in the master branch is 0.99.rc1, a release candidate for version 1.0.**
12+
13+
We consider the 1.x release of `octocatalog-diff` to be stable and production-quality. We continue to maintain and enhance `octocatalog-diff` to meet GitHub's internal needs and to incorporate suggestions from the community. Please consult the [change log](/doc/CHANGELOG.md) for details.
1214

1315
## How?
1416

@@ -58,6 +60,7 @@ The example above reflects the changes in the Puppet catalog from switching an u
5860
- [Similar tools](/doc/similar.md)
5961
- [Contributing](/.github/CONTRIBUTING.md)
6062
- [Developer documentation](/doc/dev)
63+
- [API documentation](/doc/dev/api.md)
6164

6265
## What's in a name?
6366

@@ -79,4 +82,4 @@ It requires 3rd party ruby gems found [here](/vendor/cache). It also includes po
7982

8083
## Authors
8184

82-
`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by the Site Reliability Engineering team at GitHub.
85+
`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by Kevin and the rest of the Site Reliability Engineering team at GitHub.

‎bin/octocatalog-diff‎

Lines changed: 9 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -20,56 +20,16 @@ end
2020

2121
config_test = ARGV.include?('--config-test')
2222

23-
paths = [
24-
ENV['OCTOCATALOG_DIFF_CONFIG_FILE'],
25-
File.join(Dir.pwd, '.octocatalog-diff.cfg.rb'),
26-
File.join(ENV['HOME'], '.octocatalog-diff.cfg.rb'),
27-
'/opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb',
28-
'/usr/local/etc/octocatalog-diff.cfg.rb',
29-
'/etc/octocatalog-diff.cfg.rb'
30-
]
31-
32-
cfgfile = nil
33-
34-
paths.each do |path|
35-
next if path.nil?
36-
puts "Looking for config in: #{path}" if config_test
37-
next unless File.file?(path)
38-
begin
39-
cfgfile = path
40-
puts "Loading config: #{path}" if config_test
41-
require path
42-
rescue => exc
43-
STDERR.puts "#{exc.class} error with #{path}: #{exc.message}\n#{exc.backtrace}"
44-
exit 1
45-
end
46-
break
47-
end
48-
49-
options = {}
50-
51-
if cfgfile
52-
begin
53-
options = OctocatalogDiff::Config.config
54-
rescue => exc
55-
STDERR.puts "#{exc.class} error with #{cfgfile}: #{exc.message}\n#{exc.backtrace}"
56-
exit 1
57-
end
58-
unless options.is_a?(Hash)
59-
STDERR.puts "Configuration must be Hash not #{options.class}!"
60-
exit 1
61-
end
62-
if config_test
63-
options.each do |key, val|
64-
puts ":#{key} => (#{val.class}) #{val.inspect}"
65-
end
66-
exit 0
67-
end
68-
elsif config_test
69-
STDERR.puts 'No configuration files found'
70-
exit 1
23+
logger = Logger.new(STDERR)
24+
logger.level = Logger::INFO
25+
logger.level = Logger::DEBUG if config_test
26+
27+
options = OctocatalogDiff::API::V1.config(logger: logger, test: config_test)
28+
if config_test
29+
logger.info 'Exiting now because --config-test was specified'
30+
exit(0)
7131
end
7232

7333
argv = ARGV.dup
74-
exit_code = OctocatalogDiff::CatalogDiff::Cli.cli(argv, Logger.new(STDERR), options)
34+
exit_code = OctocatalogDiff::Cli.cli(argv, Logger.new(STDERR), options)
7535
exit(exit_code)

‎doc/CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,23 @@
88
</tr>
99
</thead><tbody>
1010
<tr valign=top>
11+
<td>0.99.0rc1</td>
12+
<td>2017-01-16</td>
13+
<td>
14+
This is a release candidate for `octocatalog-diff` version 1.0. Please report any problems to us as <a href="https://github.com/github/octocatalog-diff/issues/new">in a new issue</a>.
15+
16+
The previous release (0.6.1) is available at: https://github.com/github/octocatalog-diff/tree/0.6.1
17+
18+
<h4>New Features</h4>
19+
20+
The most significant change in version 1.0 is the addition of the <a href="./dev/api.md">V1 API</a>, which permits developers to build catalogs (<code>--catalog-only</code>) and compare/diff catalogs using octocatalog-diff. Under the hood, we've rearranged the code to support these APIs, which should also improve the reliability and allow faster development cycles.
21+
22+
<h4>Breaking Changes</h4>
23+
24+
The format of the output from <code>--output-format json</code> has changed. In version 0.x of the software, each difference was represented by an array. In version 1.x, each difference is represented by a hash with meaningful English keys. We have added an option <code>--output-format legacy_json</code> if anyone depends upon the output in the old format.
25+
</td>
26+
</tr>
27+
<tr valign=top>
1128
<td>0.6.1</td>
1229
<td>2017-01-07</td>
1330
<td>

‎doc/advanced-filter.md‎

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,65 @@ Please note that there are other options to ignore specified diffs, including:
99

1010
Here is the list of available filters and an explanation of each:
1111

12-
- [YAML](#YAML) - Ignore whitespace/comment differences if YAML parses to the same object
12+
- [Absent File](/doc/advanced-filter.md#absent-file) - Ignore parameter changes of a file that is declared to be absent
13+
- [YAML](/doc/advanced-filter.md#yaml) - Ignore whitespace/comment differences if YAML parses to the same object
14+
15+
## Absent File
16+
17+
#### Usage
18+
19+
```
20+
--filters AbsentFile
21+
```
22+
23+
#### Description
24+
25+
When the `AbsentFile` filter is enabled, if any file is `ensure => absent` in the *new* catalog, then changes to any other parameters will be suppressed.
26+
27+
Consider that a file resource is declared as follows in two catalogs:
28+
29+
```
30+
# Old catalog
31+
file { '/etc/some-file':
32+
ensure => present,
33+
owner => 'root',
34+
group => 'nobody',
35+
content => 'my content here',
36+
}
37+
38+
# New catalog
39+
file { '/etc/some-file':
40+
ensure => absent,
41+
owner => 'bob',
42+
}
43+
```
44+
45+
Since the practical effect of the new catalog will be to remove the file, it doesn't matter that the owner of the (non-existent) file has changed from 'root' to 'bob', or that the content and group have changed from a string to undefined. Consider the default output without the filter:
46+
47+
```
48+
File[/etc/some-file] =>
49+
parameters =>
50+
ensure =>
51+
- present
52+
+ absent
53+
group =>
54+
- nobody
55+
owner =>
56+
- root
57+
+ bob
58+
content =>
59+
- my content here
60+
```
61+
62+
Wouldn't it be nice if the meaningless information didn't appear, and all you saw was the transition you actually care about, from present to absent? With `--filters AbsentFile` it does just this:
63+
64+
```
65+
File[/etc/some-file] =>
66+
parameters =>
67+
ensure =>
68+
- present
69+
+ absent
70+
```
1371

1472
## YAML
1573

‎doc/advanced-pe-enc.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Please see [Authentication token](https://docs.puppet.com/pe/latest/nc_forming_r
3939

4040
The referenced document contains links to generate a token with the `puppet-access` command.
4141

42-
Note that if you wish to hard-code an authentication token in your [configuration file](/doc/configuration.md), the internal variable key is `:pe_enc_token` and the content is a string containing the entire token. (The `--pe-enc-token-file` option simply reads the provided file and stores the content in the `:pe_enc_token` key. See [source](/lib/octocatalog-diff/catalog-diff/cli/options/pe_enc_token_file.rb).)
42+
Note that if you wish to hard-code an authentication token in your [configuration file](/doc/configuration.md), the internal variable key is `:pe_enc_token` and the content is a string containing the entire token. (The `--pe-enc-token-file` option simply reads the provided file and stores the content in the `:pe_enc_token` key. See [source](/lib/octocatalog-diff/cli/options/pe_enc_token_file.rb).)
4343

4444
### SSL client keypair
4545

‎doc/dev/api.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# octocatalog-diff API documentation
2+
3+
The octocatalog-diff API allows developers to construct and work with certain octocatalog-diff internals in their own projects.
4+
5+
The current API version is [API v1](/doc/dev/api/v1.md), which is available as of octocatalog-diff version 1.0.

‎doc/dev/api/v1.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# octocatalog-diff v1 API documentation
2+
3+
## API calls
4+
5+
#### catalog
6+
7+
`catalog` allows you to build a catalog using the octocatalog-diff compiler or to obtain a catalog from a Puppet server.
8+
9+
[Read more about the `catalog` call](/doc/dev/api/v1/calls/catalog.md)
10+
11+
#### catalog-diff
12+
13+
`catalog-diff` allows you compare two catalogs and obtain the differences between them. Catalogs can be built if necessary.
14+
15+
[Read more about the `catalog-diff` call](/doc/dev/api/v1/calls/catalog-diff.md)
16+
17+
#### config
18+
19+
`config` allows you read and parse an [octocatalog-diff configuration file](/doc/configuration.md).
20+
21+
[Read more about the `config` call](/doc/dev/api/v1/calls/config.md)
22+
23+
## Objects
24+
25+
#### OctocatalogDiff::API::V1::Catalog
26+
27+
The `OctocatalogDiff::API::V1::Catalog` object represents a compiled catalog and supports several methods to get information about the catalog.
28+
29+
[Read more about the `OctocatalogDiff::API::V1::Catalog` object](/doc/dev/api/v1/objects/catalog.md)
30+
31+
#### OctocatalogDiff::API::V1::Diff
32+
33+
The `OctocatalogDiff::API::V1::Diff` object represents a difference between two catalogs and supports several methods to get information about the difference.
34+
35+
[Read more about the `OctocatalogDiff::API::V1::Diff` object](/doc/dev/api/v1/objects/diff.md)
36+
37+
#### OctocatalogDiff::API::V1::FactOverride
38+
39+
The `OctocatalogDiff::API::V1::FactOverride` object represents a user-supplied fact that will be used when compiling a catalog.
40+
41+
[Read more about the `OctocatalogDiff::API::V1::FactOverride` object](/doc/dev/api/v1/objects/fact_override.md)

0 commit comments

Comments
 (0)