Skip to content

Commit 6ecb2ee

Browse files
committed
Add contributing guidelines for CI/CD and versioning
Expanded CONTRIBUTING.md with detailed guidelines: - Added purpose and intent to help contributors avoid build issues. - Documented workflow reuse conventions with examples. - Defined versioning/tagging rules aligned with SemVer/NuGet. - Provided CI version sanitization steps and usage examples. - Included troubleshooting tips for common CI issues. - Emphasized maintenance alignment with GitHub Actions/NuGet.
1 parent ea59a4f commit 6ecb2ee

1 file changed

Lines changed: 100 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Contributing Guidelines
2+
3+
## Purpose
4+
5+
This document explains project-level development and CI/CD conventions
6+
contributors must follow to avoid common build and packaging failures.
7+
8+
## Workflow Reuse Guidelines
9+
10+
### Calling a Reusable Workflow
11+
12+
- When invoking a reusable workflow using `uses:` at **job level**,
13+
**do NOT specify `runs-on`** in the caller.
14+
- The **reusable workflow must**:
15+
- Declare `on: workflow_call`
16+
- Define `runs-on` for its internal jobs
17+
- Inputs are passed via `with:`, and secrets via `secrets:`.
18+
19+
### Example: Caller (no `runs-on`)
20+
21+
``` yaml
22+
jobs:
23+
call-build:
24+
uses: ./.github/workflows/cd-build-test-pack.yml
25+
with:
26+
version: ${{ github.ref_name }}
27+
configuration: Release
28+
```
29+
30+
### Example: Reusable Workflow
31+
32+
``` yaml
33+
on:
34+
workflow_call:
35+
inputs:
36+
version:
37+
required: true
38+
type: string
39+
configuration:
40+
required: true
41+
type: string
42+
default: Release
43+
44+
jobs:
45+
build:
46+
runs-on: ubuntu-latest
47+
steps:
48+
- name: Checkout
49+
uses: actions/checkout@v4
50+
#
51+
```
52+
53+
## Versioning and Git Tag Guidelines
54+
55+
- Tags used for packaging and publishing---whether passed to
56+
`/p:Version=` or `dotnet pack`---**must be valid SemVer/NuGet
57+
version strings**.
58+
- **Do NOT include a leading `v`** when passing the version into
59+
`dotnet` commands.
60+
61+
### Valid Examples
62+
63+
- `3.2.6`
64+
- `3.2.6-preview`
65+
- `3.2.6-preview20251130229`
66+
- `3.2.6-alpha.1+build.123`
67+
68+
### Invalid Examples
69+
70+
- `v3.2.6-preview20251130229`
71+
- `3.2.6 preview`
72+
73+
### Recommended Tagging Practice
74+
75+
- Tag with leading `v` locally if desired, but CI must sanitize it.
76+
77+
## CI Behavior and Version Sanitization
78+
79+
### Sanitization Example
80+
81+
``` yaml
82+
- name: Sanitize version
83+
id: sanitize
84+
run: |
85+
v="${{ inputs.version }}"
86+
v="${v#v}"
87+
v="${v#V}"
88+
echo "sanitized_version=$v" >> "$GITHUB_OUTPUT"
89+
```
90+
91+
Use via: `${{ steps.sanitize.outputs.sanitized_version }}`
92+
93+
## Troubleshooting
94+
95+
- If CI reports "not a valid version string," check for leading `v` or
96+
invalid characters.
97+
98+
## Maintenance
99+
100+
- Keep conventions aligned with GitHub Actions and NuGet rules.

0 commit comments

Comments
 (0)