Skip to content
This repository was archived by the owner on Feb 24, 2021. It is now read-only.

Commit 49cc933

Browse files
johljujohlju
authored
Update appveyor.yml and add missing TEMPLATE_README.md (#9)
1 parent 170ff6a commit 49cc933

File tree

2 files changed

+254
-11
lines changed

2 files changed

+254
-11
lines changed

‎TEMPLATE_README.md

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# TEMPLATE README
2+
3+
This is a template that can be used as a baseline for starting your own
4+
repository containing a DSC resource module.
5+
6+
## Using the template
7+
8+
The template is used by copying all the folder and files under the folder
9+
[DscResource.Template](https://github.com/PowerShell/DscResources/tree/master/DscResource.Template)
10+
to the root of your new repository.
11+
After that you need to go through each file and update the information and code.
12+
13+
Some services should be connected to the new repository, see
14+
[Adding services to your repository](#adding-services-to-your-repository).
15+
16+
It is suggested that you add a LICENSE and CONTRIBUTING.md file to your repository
17+
as well. You should have been asked to add a license if you created the repository
18+
on GitHub (but can also be added after).
19+
20+
### Folder structure
21+
22+
```plaintext
23+
.
24+
│ .codecov.yml
25+
│ .gitattributes
26+
│ .gitignore
27+
│ .MetaTestOptIn.json
28+
│ appveyor.yml
29+
│ CHANGELOG.md
30+
│ CODE_OF_CONDUCT.md
31+
│ README.md
32+
│ ResourceModule.psd1
33+
│
34+
├───.github
35+
│ │ PULL_REQUEST_TEMPLATE.md
36+
│ │
37+
│ └───ISSUE_TEMPLATE
38+
│ General.md
39+
│ Problem_with_resource.md
40+
│ Resource_proposal.md
41+
│
42+
├───.vscode
43+
│ analyzersettings.psd1
44+
│ settings.json
45+
│
46+
├───DSCResources
47+
│ └───MSFT_ResourceName
48+
│ │ MSFT_ResourceName.psm1
49+
│ │ MSFT_ResourceName.schema.mof
50+
│ │
51+
│ └───en-US
52+
│ MSFT_ResourceName.strings.psd1
53+
│
54+
├───Examples
55+
│ └───Resources
56+
│ └───ResourceName
57+
│ 1-VeryShortDescription.ps1
58+
│
59+
├───Modules
60+
│ └───ModuleName.Common
61+
│ │ ModuleName.Common.psm1
62+
│ │
63+
│ └───en-US
64+
│ ModuleName.Common.strings.psd1
65+
│
66+
└───Tests
67+
├───Integration
68+
│ MSFT_ResourceName.config.ps1
69+
│ MSFT_ResourceName.Integration.Tests.ps1
70+
│
71+
└───Unit
72+
MSFT_ResourceName.Tests.ps1
73+
```
74+
75+
#### .codecov.yml
76+
77+
This is the settings file for the Codecov service. This contains the settings
78+
for the DSC Resource Kit.
79+
No changes are needed for this file.
80+
81+
#### .gitattributes
82+
83+
This is the settings file for git. This file is used by DSC Resource Kit to
84+
always check out the files with CRLF regardless of how `git` is configured.
85+
It must be present for the automatic publishing of examples to PowerShell Gallery
86+
to work (opt-in in the test framework, DscResource.Tests).
87+
No changes are needed for this file.
88+
89+
#### .gitignore
90+
91+
This file is used by git to ignore certain files or folders so that that they do
92+
not get committed to the repository. This file is used by the DSC Resource Kit
93+
to ignore the folder DscResource.Tests, which is automatically cloned by the unit
94+
and integration tests when using the unit and integration test templates.
95+
No changes are needed for this file.
96+
97+
#### .MetaTestOptIn.json
98+
99+
This files controls what tests are opt-in when the test framework is run, for
100+
example when run in AppVeyor.
101+
If some test are opt-out, then the test framework will output the strings to put
102+
into this file. Add those strings to this file to opt-in for those tests.
103+
No changes are needed for this file, unless opt-in to more tests.
104+
105+
#### appveyor.yml
106+
107+
This is the control file for AppVeyor (that runs the CI pipeline). This file
108+
tells AppVeyor how and what to run during the continuous integration process.
109+
If using the automatic publishing of examples, then the API key needs to be
110+
updated, otherwise the environment variable can be removed.
111+
No other changes are needed for this file.
112+
113+
#### CHANGELOG.md
114+
115+
This file is used to track changes to the resource module. Update
116+
{ModuleName} to match the name of the resource module, and update the sections
117+
to suit your needs.
118+
119+
#### CODE_OF_CONDUCT.md
120+
121+
This file explains the Code of Conduct. This file should be changed to the
122+
code of conduct that you and your contributors are to follow.
123+
124+
#### README.md
125+
126+
This file is used to show information about the repository and the
127+
documentation around the resources in the resource module.
128+
129+
Update:
130+
131+
- {ModuleName} throughout to match the name of the resource module.
132+
- { Description of the module ... } to match the description of your module.
133+
- {token} to your token for AppVeyor.
134+
- Update the section "How to contribute". Can also point to your contributing
135+
guidelines in a CONTRIBUTING.md.
136+
- Update the section Resources to match your resources.
137+
138+
#### ResourceModule.psd1
139+
140+
Rename this file, replacing 'ResourceModule', with the name of your resource
141+
module.
142+
Replace the content of the properties in this file to match your resource module.
143+
It is important to change the GUID in this file to a new unique GUID for your
144+
module (i.e by running `New-Guid` to get a unique GUID).
145+
146+
#### .github
147+
148+
This folder contains issues templates and pull request template. They are visible
149+
to the user in GitHub when a contributor is submitting an issue (they user can
150+
choose which issue template suits the issue), or when a contributor proposes a
151+
change in a pull request, the pull request template is shown.
152+
153+
#### .vscode
154+
155+
This folder contains settings file for Visual Studio Code. The settings file
156+
is used to simplify formatting and making sure the correct PS Script Analyzer
157+
rules are used.
158+
If Visual Studio Code is not used as the editor, then this folder is not
159+
necessary. No changes are needed for the files in this folder.
160+
161+
#### DSCResources
162+
163+
This folder contains the actual resource(s) in this resource module.
164+
165+
#### Modules
166+
167+
This folder is meant to contain PowerShell modules that holds helper functions
168+
used by more than one resource. Using this folder for helper functions make sure
169+
the test framework finds the module files and shows coverage for the code.
170+
171+
#### Examples
172+
173+
This folder contains the examples of using the resources. These example can
174+
be published automatically to PowerShell Gallery (if opt-in).
175+
176+
#### Tests
177+
178+
This folder holds unit tests and integration tests used to test the resources
179+
and helper function in this resource module.
180+
181+
##### Integration
182+
183+
This folder should contain the integration tests. An integration test is a test
184+
that make actual changes to the environment to test the functionality.
185+
186+
By separating integration tests from the unit tests, the unit test can be run
187+
without the fear that a test could potentially make destructive
188+
changes to the environment.
189+
190+
##### Unit
191+
192+
This folder should contain the unit tests. A unit test is a test
193+
that _does not_ make changes to the environment. Instead, a unit test mocks
194+
the command that would make the actual change, making it possible to test
195+
functionality in several code paths.
196+
Unit tests should be safe to run on any environment.
197+
198+
By separating integration tests from the unit tests, the unit test can be run
199+
without the fear that a test could potentially make destructive
200+
changes to the environment.
201+
202+
## Adding services to your repository
203+
204+
The template assumes some free services (for open source projects on GitHub) are
205+
used. You should connect to the services to get the most out of the test framework.
206+
207+
- **AppVeyor** - to run automated tests
208+
- **Codecov** - to get code coverage on PR's and project.
209+
- **PowerShell Gallery** - to publish examples automatically.
210+
211+
## Plaster
212+
213+
There is also a community project to create a Plaster template for generating
214+
a baseline for a DSC resource module. Please see the GitHub repository
215+
[NewDscHighQualityResourceModule](https://github.com/bgelens/NewDscHighQualityResourceModule)
216+
for more information.
217+
218+
## Change log
219+
220+
This is the change log for DscResource.Template. Any changes to the
221+
DscResource.Template should be mentioned here for reference by the users.
222+
223+
### 2019-02-03
224+
225+
- Initial commit to repository DscResource.Template.
226+
227+
### 2018-09-22
228+
229+
- The file appveyor.yml correctly uses named parameters for PowerShell cmdlets.
230+
231+
### 2018-09-20
232+
233+
- Added GitHub standard issue templates and pull request template.
234+
235+
### 2018-09-06
236+
237+
- Added change log for DscResource.Template, there were no change log prior to
238+
this date.
239+
- Added the CODE_OF_CONDUCT.md and updated text for code of conduct in README.md.

‎appveyor.yml

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,33 +5,37 @@
55
# This template assumes you have connected your repository to AppVeyor
66
# (https://ci.appveyor.com).
77
#
8-
# Before using it in your repository, modify places marked with 'TODO:'.
8+
# Before using it in your repository, modify places marked with 'TODO:', and
9+
# then remove this comment block.
910
################################################################################
1011

12+
1113
#---------------------------------#
1214
# environment configuration #
1315
#---------------------------------#
1416

1517
version: 1.0.{build}.0 # TODO: Modify version so it fits your versioning.
16-
1718
environment:
1819
gallery_api:
19-
secure: uwd5h4xufRG6/4wEOUIrdEeTkXYIiLFydKXhP5ZKv5j8rR2acKOHrsL7c2UoYmZQ
20-
21-
init:
22-
# Needed for publishing of examples, build worker defaults to core.autocrlf=input.
23-
- git config --global core.autocrlf true
20+
# TODO: Change to the correct API key if using PowerShell Gallery deploy task.
21+
# If you wish to use this to publish your own module you'd need to set your
22+
# own API key (encrypted by https://ci.appveyor.com/tools/encrypt).
23+
#
24+
# This API key can only be decrypted by the PowerShell Team's AppVeyor account,
25+
# and can only be used for resource modules under the DSC Resource Kit.
26+
secure: 9ekJzfsPCDBkyLrfmov83XbbhZ6E2N3z+B/Io8NbDetbHc6hWS19zsDmy7t0Vvxv
2427

2528
install:
2629
- ps: |
30+
# TODO: Remove these 4 rows.
2731
# This is workaround for AppVeyor replaces '.' with '-' in the folder name.
2832
Set-Location -Path 'C:\projects'
2933
Rename-Item -Path 'C:\projects\dscresource-template' -NewName 'DscResource.Template' -Force
3034
$env:APPVEYOR_BUILD_FOLDER = 'C:\projects\DscResource.Template'
3135
Set-Location -Path $env:APPVEYOR_BUILD_FOLDER
3236
- git clone https://github.com/PowerShell/DscResource.Tests
3337
- ps: Write-Verbose -Message "PowerShell version $($PSVersionTable.PSVersion)" -Verbose
34-
- ps: Import-Module "$env:APPVEYOR_BUILD_FOLDER\DscResource.Tests\AppVeyor.psm1"
38+
- ps: Import-Module -Name "$env:APPVEYOR_BUILD_FOLDER\DscResource.Tests\AppVeyor.psm1"
3539
- ps: Invoke-AppveyorInstallTask
3640

3741
#---------------------------------#
@@ -49,12 +53,12 @@ test_script:
4953
# TODO:
5054
# To use -CodeCovIo parameter, the repository need to connected
5155
# to Codecov (see https://codecov.io/).
52-
Invoke-AppveyorTestScriptTask -CodeCoverage -CodeCovIo -ExcludeTag @()
56+
Invoke-AppveyorTestScriptTask -CodeCoverage -CodeCovIo
5357
54-
# scripts to run before deployment.
58+
# scripts to run before deployment
5559
after_test:
5660
- ps: |
57-
Write-Verbose -Message "Branch: $env:APPVEYOR_REPO_BRANCH" -Verbose
61+
Import-Module -Name "$env:APPVEYOR_BUILD_FOLDER\DscResource.Tests\AppVeyor.psm1"
5862
Invoke-AppveyorAfterTestTask
5963
6064
#---------------------------------#

0 commit comments

Comments
 (0)