puppet 6.13.0 → 6.14.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of puppet might be problematic. Click here for more details.

Files changed (118) hide show
  1. checksums.yaml +4 -4
  2. data/CONTRIBUTING.md +7 -13
  3. data/Gemfile.lock +6 -6
  4. data/README.md +15 -22
  5. data/lib/puppet.rb +1 -1
  6. data/lib/puppet/application/agent.rb +9 -11
  7. data/lib/puppet/application/describe.rb +7 -5
  8. data/lib/puppet/application/device.rb +2 -2
  9. data/lib/puppet/application/filebucket.rb +14 -1
  10. data/lib/puppet/application/ssl.rb +1 -1
  11. data/lib/puppet/configurer.rb +30 -41
  12. data/lib/puppet/configurer/plugin_handler.rb +10 -1
  13. data/lib/puppet/defaults.rb +7 -1
  14. data/lib/puppet/face/plugin.rb +1 -1
  15. data/lib/puppet/functions/eyaml_lookup_key.rb +13 -8
  16. data/lib/puppet/http.rb +1 -0
  17. data/lib/puppet/http/client.rb +69 -34
  18. data/lib/puppet/http/resolver/server_list.rb +2 -2
  19. data/lib/puppet/http/resolver/settings.rb +1 -1
  20. data/lib/puppet/http/resolver/srv.rb +1 -1
  21. data/lib/puppet/http/response.rb +6 -1
  22. data/lib/puppet/http/service.rb +30 -11
  23. data/lib/puppet/http/service/ca.rb +8 -8
  24. data/lib/puppet/http/service/compiler.rb +41 -10
  25. data/lib/puppet/http/service/file_server.rb +40 -20
  26. data/lib/puppet/http/service/report.rb +12 -15
  27. data/lib/puppet/http/session.rb +39 -1
  28. data/lib/puppet/indirector/catalog/rest.rb +33 -0
  29. data/lib/puppet/indirector/facts/rest.rb +41 -0
  30. data/lib/puppet/indirector/file_content/rest.rb +30 -0
  31. data/lib/puppet/indirector/file_metadata/rest.rb +50 -0
  32. data/lib/puppet/indirector/node/rest.rb +23 -0
  33. data/lib/puppet/indirector/report/rest.rb +19 -0
  34. data/lib/puppet/indirector/rest.rb +6 -0
  35. data/lib/puppet/indirector/status/rest.rb +17 -0
  36. data/lib/puppet/loaders.rb +6 -0
  37. data/lib/puppet/network/http/base_pool.rb +1 -1
  38. data/lib/puppet/network/http/pool.rb +6 -1
  39. data/lib/puppet/provider/group/groupadd.rb +9 -4
  40. data/lib/puppet/runtime.rb +8 -1
  41. data/lib/puppet/settings.rb +2 -0
  42. data/lib/puppet/settings/http_extra_headers_setting.rb +25 -0
  43. data/lib/puppet/ssl/state_machine.rb +4 -0
  44. data/lib/puppet/test/test_helper.rb +3 -1
  45. data/lib/puppet/type/file.rb +13 -0
  46. data/lib/puppet/type/file/source.rb +47 -58
  47. data/lib/puppet/version.rb +1 -1
  48. data/locales/puppet.pot +167 -160
  49. data/man/man5/puppet.conf.5 +11 -3
  50. data/man/man8/puppet-agent.8 +6 -6
  51. data/man/man8/puppet-apply.8 +1 -1
  52. data/man/man8/puppet-catalog.8 +1 -1
  53. data/man/man8/puppet-config.8 +1 -1
  54. data/man/man8/puppet-describe.8 +1 -1
  55. data/man/man8/puppet-device.8 +2 -2
  56. data/man/man8/puppet-doc.8 +1 -1
  57. data/man/man8/puppet-epp.8 +1 -1
  58. data/man/man8/puppet-facts.8 +1 -1
  59. data/man/man8/puppet-filebucket.8 +17 -2
  60. data/man/man8/puppet-generate.8 +1 -1
  61. data/man/man8/puppet-help.8 +1 -1
  62. data/man/man8/puppet-key.8 +1 -1
  63. data/man/man8/puppet-lookup.8 +1 -1
  64. data/man/man8/puppet-man.8 +1 -1
  65. data/man/man8/puppet-module.8 +1 -1
  66. data/man/man8/puppet-node.8 +1 -1
  67. data/man/man8/puppet-parser.8 +1 -1
  68. data/man/man8/puppet-plugin.8 +1 -1
  69. data/man/man8/puppet-report.8 +1 -1
  70. data/man/man8/puppet-resource.8 +1 -1
  71. data/man/man8/puppet-script.8 +1 -1
  72. data/man/man8/puppet-ssl.8 +2 -2
  73. data/man/man8/puppet-status.8 +1 -1
  74. data/man/man8/puppet.8 +2 -2
  75. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_md5/should_fetch_if_not_on_the_local_disk.yml +1 -67
  76. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_md5/should_not_update_if_content_on_disk_is_up-to-date.yml +1 -69
  77. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_md5/should_update_if_content_differs_on_disk.yml +1 -69
  78. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_mtime/should_fetch_if_mtime_is_older_on_disk.yml +1 -67
  79. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_mtime/should_fetch_if_no_header_specified.yml +1 -65
  80. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_mtime/should_fetch_if_not_on_the_local_disk.yml +1 -67
  81. data/spec/fixtures/vcr/cassettes/Puppet_Type_File/when_sourcing/from_http/using_mtime/should_not_update_if_mtime_is_newer_on_disk.yml +1 -67
  82. data/spec/integration/faces/plugin_spec.rb +3 -1
  83. data/spec/integration/http/client_spec.rb +11 -0
  84. data/spec/integration/network/http_pool_spec.rb +9 -1
  85. data/spec/unit/application/describe_spec.rb +88 -50
  86. data/spec/unit/configurer/plugin_handler_spec.rb +36 -19
  87. data/spec/unit/configurer_spec.rb +16 -14
  88. data/spec/unit/face/plugin_spec.rb +12 -10
  89. data/spec/unit/functions/lookup_spec.rb +13 -0
  90. data/spec/unit/http/client_spec.rb +172 -1
  91. data/spec/unit/http/resolver_spec.rb +14 -2
  92. data/spec/unit/http/response_spec.rb +69 -0
  93. data/spec/unit/http/service/ca_spec.rb +28 -9
  94. data/spec/unit/http/service/compiler_spec.rb +151 -24
  95. data/spec/unit/http/service/file_server_spec.rb +65 -8
  96. data/spec/unit/http/service/report_spec.rb +17 -8
  97. data/spec/unit/http/service_spec.rb +92 -3
  98. data/spec/unit/http/session_spec.rb +104 -1
  99. data/spec/unit/indirector/catalog/rest_spec.rb +59 -2
  100. data/spec/unit/indirector/facts/rest_spec.rb +79 -24
  101. data/spec/unit/indirector/file_content/rest_spec.rb +53 -2
  102. data/spec/unit/indirector/file_metadata/rest_spec.rb +109 -2
  103. data/spec/unit/indirector/node/rest_spec.rb +57 -2
  104. data/spec/unit/indirector/report/rest_spec.rb +58 -51
  105. data/spec/unit/indirector/resource/ral_spec.rb +7 -8
  106. data/spec/unit/indirector/status/rest_spec.rb +43 -2
  107. data/spec/unit/network/http/pool_spec.rb +57 -11
  108. data/spec/unit/provider/group/groupadd_spec.rb +22 -8
  109. data/spec/unit/settings/autosign_setting_spec.rb +1 -1
  110. data/spec/unit/settings/http_extra_headers_spec.rb +64 -0
  111. data/spec/unit/ssl/state_machine_spec.rb +10 -0
  112. data/spec/unit/transaction_spec.rb +0 -2
  113. data/spec/unit/type/file/ensure_spec.rb +1 -2
  114. data/spec/unit/type/file/source_spec.rb +86 -35
  115. data/spec/unit/util/at_fork_spec.rb +1 -0
  116. data/spec/unit/util/pidlock_spec.rb +36 -24
  117. metadata +7 -3
  118. data/COMMITTERS.md +0 -244
@@ -5,6 +5,7 @@ describe 'Puppet::Util::AtFork' do
5
5
 
6
6
  before :each do
7
7
  Puppet::Util.class_exec do
8
+ remove_const(:AtFork) if defined?(Puppet::Util::AtFork)
8
9
  const_set(:AtFork, Module.new)
9
10
  end
10
11
  end
@@ -9,27 +9,39 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
9
9
  before(:each) do
10
10
  @lockfile = tmpfile("lock")
11
11
  @lock = Puppet::Util::Pidlock.new(@lockfile)
12
- @ps_argument_for_current_kernel = @lock.send(:ps_argument_for_current_kernel)
12
+ allow(Facter).to receive(:value).with(:kernel).and_return('Linux')
13
13
  end
14
14
 
15
15
  describe "#ps pid argument on posix", unless: Puppet::Util::Platform.windows? do
16
- before(:each) do
16
+ it "should fallback to '-p' when ps execution fails with '-eq' on Linux" do
17
17
  @lock.lock
18
- end
18
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'comm=']).and_raise(Puppet::ExecutionFailure, 'Execution of command returned 1: error')
19
19
 
20
- it "should allow ps execution" do
21
- expect { Puppet::Util::Execution.execute(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'comm=']) }.not_to raise_error
22
- expect { Puppet::Util::Execution.execute(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'args=']) }.not_to raise_error
20
+ expect(Puppet::Util::Execution).to receive(:execute).with(['ps', "-p", @lock.lock_pid, '-o', 'comm=']).and_return('puppet')
21
+ expect(Puppet::Util::Execution).to receive(:execute).with(['ps', "-p", @lock.lock_pid, '-o', 'args=']).and_return('puppet')
23
22
  expect(@lock).to be_locked
24
23
  end
25
24
 
26
- it "should fallback to -p when default argument fails ps execution" do
27
- allow(@lock).to receive(:ps_argument_for_current_kernel).and_return("-eq")
28
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', "-eq", @lock.lock_pid, '-o', 'comm=']).and_raise(Puppet::ExecutionFailure, 'Execution of command returned 1: error')
25
+ shared_examples_for 'a valid ps argument was provided' do |desired_kernel, ps_argument|
26
+ it "should be '#{ps_argument}' when current kernel is #{desired_kernel}" do
27
+ @lock.lock
28
+ allow(Facter).to receive(:value).with(:kernel).and_return(desired_kernel)
29
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', ps_argument, @lock.lock_pid, '-o', 'comm=']).and_return('ruby')
30
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', ps_argument, @lock.lock_pid, '-o', 'args=']).and_return('puppet')
31
+ expect(@lock).to be_locked
32
+ end
33
+ end
29
34
 
30
- expect(Puppet::Util::Execution).to receive(:execute).with(['ps', "-p", @lock.lock_pid, '-o', 'comm=']).and_return('puppet')
31
- expect(Puppet::Util::Execution).to receive(:execute).with(['ps', "-p", @lock.lock_pid, '-o', 'args=']).and_return('puppet')
32
- expect(@lock).to be_locked
35
+ context "when current kernel is Linux" do
36
+ it_should_behave_like 'a valid ps argument was provided', "Linux", "-eq"
37
+ end
38
+
39
+ context "when current kernel is AIX" do
40
+ it_should_behave_like 'a valid ps argument was provided', "AIX", "-T"
41
+ end
42
+
43
+ context "when current kernel is Darwin" do
44
+ it_should_behave_like 'a valid ps argument was provided', "Darwin", "-p"
33
45
  end
34
46
  end
35
47
 
@@ -47,8 +59,8 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
47
59
  if Puppet::Util::Platform.windows?
48
60
  allow(Puppet::Util::Windows::Process).to receive(:get_process_image_name_by_pid).with(@lock.lock_pid).and_return('C:\Program Files\Puppet Labs\Puppet\puppet\bin\ruby.exe')
49
61
  else
50
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'comm=']).and_return('puppet')
51
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'args=']).and_return('puppet')
62
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'comm=']).and_return('puppet')
63
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'args=']).and_return('puppet')
52
64
  end
53
65
  expect(@lock).to be_locked
54
66
  end
@@ -58,8 +70,8 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
58
70
  if Puppet::Util::Platform.windows?
59
71
  allow(Puppet::Util::Windows::Process).to receive(:get_process_image_name_by_pid).with(@lock.lock_pid).and_return('C:\tools\ruby25\bin\ruby.exe')
60
72
  else
61
- expect(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'comm=']).and_return('ruby')
62
- expect(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'args=']).and_return('ruby /root/puppet/.bundle/ruby/2.3.0/bin/puppet agent --no-daemonize -v')
73
+ expect(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'comm=']).and_return('ruby')
74
+ expect(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'args=']).and_return('ruby /root/puppet/.bundle/ruby/2.3.0/bin/puppet agent --no-daemonize -v')
63
75
  end
64
76
  expect(@lock).to be_locked
65
77
  end
@@ -142,8 +154,8 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
142
154
  if Puppet::Util::Platform.windows?
143
155
  allow(Puppet::Util::Windows::Process).to receive(:get_process_image_name_by_pid).with(@lock.lock_pid).and_return('C:\Program Files\Puppet Labs\Puppet\puppet\bin\ruby.exe')
144
156
  else
145
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'comm=']).and_return('puppet')
146
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'args=']).and_return('puppet')
157
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'comm=']).and_return('puppet')
158
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'args=']).and_return('puppet')
147
159
  end
148
160
  expect(@lock).to be_locked
149
161
  end
@@ -153,8 +165,8 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
153
165
  if Puppet::Util::Platform.windows?
154
166
  allow(Puppet::Util::Windows::Process).to receive(:get_process_image_name_by_pid).with(@lock.lock_pid).and_return('C:\tools\ruby25\bin\ruby.exe')
155
167
  else
156
- expect(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'comm=']).and_return('ruby')
157
- expect(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, @lock.lock_pid, '-o', 'args=']).and_return('ruby /root/puppet/.bundle/ruby/2.3.0/bin/puppet agent --no-daemonize -v')
168
+ expect(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'comm=']).and_return('ruby')
169
+ expect(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', @lock.lock_pid, '-o', 'args=']).and_return('ruby /root/puppet/.bundle/ruby/2.3.0/bin/puppet agent --no-daemonize -v')
158
170
  end
159
171
  expect(@lock).to be_locked
160
172
  end
@@ -204,8 +216,8 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
204
216
  if Puppet::Util::Platform.windows?
205
217
  allow(Puppet::Util::Windows::Process).to receive(:get_process_image_name_by_pid).with(6789).and_return('C:\Program Files\Puppet Labs\Puppet\puppet\bin\ruby.exe')
206
218
  else
207
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, 6789, '-o', 'comm=']).and_return('puppet')
208
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, 6789, '-o', 'args=']).and_return('puppet')
219
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', 6789, '-o', 'comm=']).and_return('puppet')
220
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', 6789, '-o', 'args=']).and_return('puppet')
209
221
  end
210
222
  @lock.lock
211
223
  expect(Puppet::FileSystem.exist?(@lockfile)).to be_truthy
@@ -234,8 +246,8 @@ describe Puppet::Util::Pidlock, if: !Puppet::Util::Platform.jruby? do
234
246
  if Puppet::Util::Platform.windows?
235
247
  allow(Puppet::Util::Windows::Process).to receive(:get_process_image_name_by_pid).with(1234).and_return('C:\Program Files\Puppet Labs\Puppet\puppet\bin\ruby.exe')
236
248
  else
237
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, 1234, '-o', 'comm=']).and_return('puppet')
238
- allow(Puppet::Util::Execution).to receive(:execute).with(['ps', @ps_argument_for_current_kernel, 1234, '-o', 'args=']).and_return('puppet')
249
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', 1234, '-o', 'comm=']).and_return('puppet')
250
+ allow(Puppet::Util::Execution).to receive(:execute).with(['ps', '-eq', 1234, '-o', 'args=']).and_return('puppet')
239
251
  end
240
252
  # lock the file
241
253
  @lock.lock
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: puppet
3
3
  version: !ruby/object:Gem::Version
4
- version: 6.13.0
4
+ version: 6.14.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Puppet Labs
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2020-02-17 00:00:00.000000000 Z
11
+ date: 2020-03-07 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: facter
@@ -171,7 +171,6 @@ extra_rdoc_files: []
171
171
  files:
172
172
  - CODEOWNERS
173
173
  - CODE_OF_CONDUCT.md
174
- - COMMITTERS.md
175
174
  - CONTRIBUTING.md
176
175
  - Gemfile
177
176
  - Gemfile.lock
@@ -1148,6 +1147,7 @@ files:
1148
1147
  - lib/puppet/settings/errors.rb
1149
1148
  - lib/puppet/settings/file_or_directory_setting.rb
1150
1149
  - lib/puppet/settings/file_setting.rb
1150
+ - lib/puppet/settings/http_extra_headers_setting.rb
1151
1151
  - lib/puppet/settings/ini_file.rb
1152
1152
  - lib/puppet/settings/path_setting.rb
1153
1153
  - lib/puppet/settings/priority_setting.rb
@@ -2079,6 +2079,7 @@ files:
2079
2079
  - spec/unit/hiera_puppet_spec.rb
2080
2080
  - spec/unit/http/client_spec.rb
2081
2081
  - spec/unit/http/resolver_spec.rb
2082
+ - spec/unit/http/response_spec.rb
2082
2083
  - spec/unit/http/service/ca_spec.rb
2083
2084
  - spec/unit/http/service/compiler_spec.rb
2084
2085
  - spec/unit/http/service/file_server_spec.rb
@@ -2462,6 +2463,7 @@ files:
2462
2463
  - spec/unit/settings/enum_setting_spec.rb
2463
2464
  - spec/unit/settings/environment_conf_spec.rb
2464
2465
  - spec/unit/settings/file_setting_spec.rb
2466
+ - spec/unit/settings/http_extra_headers_spec.rb
2465
2467
  - spec/unit/settings/ini_file_spec.rb
2466
2468
  - spec/unit/settings/path_setting_spec.rb
2467
2469
  - spec/unit/settings/priority_setting_spec.rb
@@ -3336,6 +3338,7 @@ test_files:
3336
3338
  - spec/unit/hiera_puppet_spec.rb
3337
3339
  - spec/unit/http/client_spec.rb
3338
3340
  - spec/unit/http/resolver_spec.rb
3341
+ - spec/unit/http/response_spec.rb
3339
3342
  - spec/unit/http/service/ca_spec.rb
3340
3343
  - spec/unit/http/service/compiler_spec.rb
3341
3344
  - spec/unit/http/service/file_server_spec.rb
@@ -3719,6 +3722,7 @@ test_files:
3719
3722
  - spec/unit/settings/enum_setting_spec.rb
3720
3723
  - spec/unit/settings/environment_conf_spec.rb
3721
3724
  - spec/unit/settings/file_setting_spec.rb
3725
+ - spec/unit/settings/http_extra_headers_spec.rb
3722
3726
  - spec/unit/settings/ini_file_spec.rb
3723
3727
  - spec/unit/settings/path_setting_spec.rb
3724
3728
  - spec/unit/settings/priority_setting_spec.rb
@@ -1,244 +0,0 @@
1
- Committing changes to Puppet
2
- ====
3
-
4
- We would like to make it easier for community members to contribute to Puppet
5
- using pull requests, even if it makes the task of reviewing and committing
6
- these changes a little harder. Pull requests are only ever based on a single
7
- branch, however, we maintain more than one active branch. As a result
8
- contributors should target their changes at the master branch. This makes the
9
- process of contributing a little easier for the contributor since they don't
10
- need to concern themselves with the question, "What branch do I base my changes
11
- on?" This is already called out in the [CONTRIBUTING.md](https://goo.gl/XRH2J).
12
-
13
- Therefore, it is the responsibility of the committer to re-base the change set
14
- on the appropriate branch which should receive the contribution.
15
-
16
- It is also the responsibility of the committer to review the change set in an
17
- effort to make sure the end users must opt-in to new behavior that is
18
- incompatible with previous behavior. We employ the use of [feature
19
- flags](https://stackoverflow.com/questions/7707383/what-is-a-feature-flag) as
20
- the primary way to achieve this user opt-in behavior. Finally, it is the
21
- responsibility of the committer to make sure the `master` and `stable` branches
22
- are both clean and working at all times. Clean means that dead code is not
23
- allowed, everything needs to be usable in some manner at all points in time.
24
- Stable is not an indication of the build status, but rather an expression of
25
- our intent that the `stable` branch does not receive new functionality.
26
-
27
- The rest of this document addresses the concerns of the committer. This
28
- document will help guide the committer decide which branch to base, or re-base
29
- a contribution on top of. This document also describes our branch management
30
- strategy, which is closely related to the decision of what branch to commit
31
- changes into.
32
-
33
- Terminology
34
- ====
35
-
36
- Many of these terms have more than one meaning. For the purposes of this
37
- document, the following terms refer to specific things.
38
-
39
- **contributor** - A person who makes a change to Puppet and submits a change
40
- set in the form of a pull request.
41
-
42
- **change set** - A set of discrete patches which combined together form a
43
- contribution. A change set takes the form of Git commits and is submitted to
44
- Puppet in the form of a pull request.
45
-
46
- **committer** - A person responsible for reviewing a pull request and then
47
- making the decision what base branch to merge the change set into.
48
-
49
- **base branch** - A branch in Git that contains an active history of changes
50
- and will eventually be released using semantic version guidelines. The branch
51
- named `master` will always exist as a base branch. The other base branches are
52
- `stable`, and `security` described below.
53
-
54
- **master branch** - The branch where new functionality that are not bug fixes
55
- is merged.
56
-
57
- **stable branch** - The branch where bug fixes against the latest release or
58
- release candidate are merged.
59
-
60
- **security** - Where critical security fixes are merged. These change sets
61
- will then be merged into release branches independently from one another. (i.e.
62
- no merging up). Please do not submit pull requests against the security branch
63
- and instead report all security related issues to security@puppetlabs.com as
64
- per our security policy published at
65
- [https://puppetlabs.com/security/](https://puppetlabs.com/security/).
66
-
67
- Committer Guide
68
- ====
69
-
70
- This section provides a guide to follow while committing change sets to Puppet
71
- base branches.
72
-
73
- How to decide what release(s) should be patched
74
- ---
75
-
76
- This section provides a guide to help a committer decide the specific base
77
- branch that a change set should be merged into.
78
-
79
- The latest minor release of a major release is the only base branch that should
80
- be patched. These patches will be merged into `master` if they contain new
81
- functionality. They will be merged into `stable` and `master` if they fix a
82
- critical bug. Older minor releases in a major release do not get patched.
83
-
84
- Before the switch to [semantic versions](http://semver.org/) committers did not
85
- have to think about the difference between minor and major releases.
86
- Committing to the latest minor release of a major release is a policy intended
87
- to limit the number of active base branches that must be managed.
88
-
89
- Security patches are handled as a special case. Security patches may be
90
- applied to earlier minor releases of a major release, but the patches should
91
- first be merged into the `security` branch. Security patches should be merged
92
- by Puppet Labs staff members. Pull requests should not be submitted with the
93
- security branch as the base branch. Please send all security related
94
- information or patches to security@puppetlabs.com as per our [Security
95
- Policy](https://puppetlabs.com/security/).
96
-
97
- The CI systems are configured to run against `master` and `stable`. Over time,
98
- these branches will refer to different versions, but their name will remain
99
- fixed to avoid having to update CI jobs and tasks as new versions are released.
100
-
101
- How to commit a change set to multiple base branches
102
- ---
103
-
104
- A change set may apply to multiple branches, for example a bug fix should be
105
- applied to the stable release and the development branch. In this situation
106
- the change set needs to be committed to multiple base branches. This section
107
- provides a guide for how to merge patches into these branches, e.g.
108
- `stable` is patched, how should the changes be applied to `master`?
109
-
110
- First, rebase the change set onto the `stable` branch. Next, merge the change
111
- set into the `stable` branch using a merge commit. Once merged into `stable`,
112
- merge the same change set into `master` without doing a rebase as to preserve
113
- the commit identifiers. This merge strategy follows the [git
114
- flow](http://nvie.com/posts/a-successful-git-branching-model/) model. Both of
115
- these change set merges should have a merge commit which makes it much easier
116
- to track a set of commits as a logical change set through the history of a
117
- branch. Merge commits should be created using the `--no-ff --log` git merge
118
- options.
119
-
120
- Any merge conflicts should be resolved using the merge commit in order to
121
- preserve the commit identifiers for each individual change. This ensures `git
122
- branch --contains` will accurately report all of the base branches which
123
- contain a specific patch.
124
-
125
- Using this strategy, the stable branch need not be reset. Both `master` and
126
- `stable` have infinite lifetimes. Patch versions, also known as bug fix
127
- releases, will be tagged and released directly from the `stable` branch. Major
128
- and minor versions, also known as feature releases, will be tagged and released
129
- directly from the `master` branch. Upon release of a new major or minor
130
- version all of the changes in the `master` branch will be merged into the
131
- `stable` branch.
132
-
133
- Code review checklist
134
- ---
135
-
136
- This section aims to provide a checklist of things to look for when reviewing a
137
- pull request and determining if the change set should be merged into a base
138
- branch:
139
-
140
- * All tests pass
141
- * Are there any platform gotchas? (Does a change make an assumption about
142
- platform specific behavior that is incompatible with other platforms? e.g.
143
- Windows paths vs. POSIX paths.)
144
- * Is the change backwards compatible? (It should be)
145
- * Are there YARD docs for API changes?
146
- * Does the change set also require documentation changes? If so is the
147
- documentation being kept up to date?
148
- * Does the change set include clean code? (software code that is formatted
149
- correctly and in an organized manner so that another coder can easily read
150
- or modify it.) HINT: `git diff master --check`
151
- * Does the change set conform to the contributing guide?
152
-
153
- Commit citizen guidelines:
154
- ---
155
-
156
- This section aims to provide guidelines for being a good commit citizen by
157
- paying attention to our automated build tools.
158
-
159
- * Don’t push on a broken build. (A broken build is defined as a failing job
160
- in the [Puppet FOSS](https://jenkins.puppetlabs.com/view/Puppet%20FOSS/)
161
- page.)
162
- * Watch the build until your changes have gone through green
163
- * Update the ticket status and target version. The target version field in
164
- our issue tracker should be updated to be the next release of Puppet. For
165
- example, if the most recent release of Puppet is 3.1.1 and you merge a
166
- backwards compatible change set into master, then the target version should
167
- be 3.2.0 in the issue tracker.)
168
- * Ensure the pull request is closed (Hint: amend your merge commit to contain
169
- the string `closes #123` where 123 is the pull request number and github
170
- will automatically close the pull request when the branch is pushed.)
171
-
172
- Example Procedure
173
- ====
174
-
175
- This section helps a committer rebase a contribution onto an earlier base
176
- branch, then merge into the base branch and up through all active base
177
- branches.
178
-
179
- Suppose a contributor submits a pull request based on master. The change set
180
- fixes a bug reported against Puppet 3.1.1 which is the most recently released
181
- version of Puppet.
182
-
183
- In this example the committer should rebase the change set onto the `stable`
184
- branch since this is a bug rather than new functionality.
185
-
186
- First, the committer pulls down the branch using the `hub` gem. This tool
187
- automates the process of adding the remote repository and creating a local
188
- branch to track the remote branch.
189
-
190
- $ hub checkout https://github.com/puppetlabs/puppet/pull/1234
191
- Branch jeffmccune-fix_foo_error set up to track remote branch fix_foo_error from jeffmccune.
192
- Switched to a new branch 'jeffmccune-fix_foo_error'
193
-
194
- At this point the topic branch is a descendant of master, but we want it to
195
- descend from `stable`. The committer rebases the change set onto `stable`.
196
-
197
- $ git branch bug/stable/fix_foo_error
198
- $ git rebase --onto stable master bug/stable/fix_foo_error
199
- First, rewinding head to replay your work on top of it...
200
- Applying: (#23456) Fix FooError that always bites users in 3.1.1
201
-
202
- The `git rebase` command may be interpreted as, "First, check out the branch
203
- named `bug/stable/fix_foo_error`, then take the changes that were previously
204
- based on `master` and re-base them onto `stable`.
205
-
206
- Now that we have a topic branch containing the change set based on the `stable`
207
- release branch, the committer merges in:
208
-
209
- $ git checkout stable
210
- Switched to branch 'stable'
211
- $ git merge --no-ff --log bug/stable/fix_foo_error
212
- Merge made by the 'recursive' strategy.
213
- foo | 0
214
- 1 file changed, 0 insertions(+), 0 deletions(-)
215
- create mode 100644 foo
216
-
217
- Once merged into the first base branch, the committer merges the `stable`
218
- branch into `master`, being careful to preserve the same commit identifiers.
219
-
220
- $ git checkout master
221
- Switched to branch 'master'
222
- $ git merge --no-ff --log stable
223
- Merge made by the 'recursive' strategy.
224
- foo | 0
225
- 1 file changed, 0 insertions(+), 0 deletions(-)
226
- create mode 100644 foo
227
-
228
- Once the change set has been merged into one base branch, the change set should
229
- not be modified in order to keep the history clean, avoid "double" commits, and
230
- preserve the usefulness of `git branch --contains`. If there are any merge
231
- conflicts, they are to be resolved in the merge commit itself and not by
232
- re-writing (rebasing) the patches for one base branch, but not another.
233
-
234
- Once the change set has been merged into `stable` and into `master`, the
235
- committer pushes. Please note, the checklist should be complete at this point.
236
- It's helpful to make sure your local branches are up to date to avoid one of
237
- the branches failing to fast forward while the other succeeds. Both the
238
- `stable` and `master` branches are being pushed at the same time.
239
-
240
- $ git push puppetlabs master:master stable:stable
241
-
242
- That's it! The committer then updates the pull request, updates the issue in
243
- our issue tracker, and keeps an eye on the [build
244
- status](http://jenkins.puppetlabs.com).