You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .vortex/docs/content/workflows/releasing.mdx
+292-1Lines changed: 292 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,4 +5,295 @@ sidebar_position: 5
5
5
6
6
# Releasing
7
7
8
-
The documentation section is still a work in progress.
8
+
Software releases are a critical part of the development lifecycle. A well-structured release process ensures code quality, minimizes deployment risks, and maintains clear communication across teams.
9
+
10
+
A typical release process consists of several key components:
11
+
12
+
1.**Release Manager** - A person or team responsible for coordinating and executing releases
13
+
2.**Release Flow** - The sequence of environments and steps code goes through from development to production
14
+
3.**Versioning Workflow** - The branching strategy that governs how code moves through environments (GitFlow being the most common)
15
+
4.**Version Scheme** - The numbering system used to identify releases (CalVer, SemVer, or custom)
16
+
5.**Release Documentation** - Runsheets, checklists, and procedures stored in accessible locations
17
+
6.**Automated Deployment** - CI/CD pipelines that handle the technical deployment process
18
+
19
+
**Vortex** provides comprehensive support for all these components, with sensible defaults and integration points for popular hosting platforms.
20
+
21
+
## Release Flow
22
+
23
+
Projects typically follow a three-tier environment strategy with clear directional flows:
24
+
25
+
```mermaid
26
+
graph LR
27
+
Dev[Development] -->|code| Stage[Stage]
28
+
Stage -->|code| Prod[Production]
29
+
Prod -.->|database| Stage
30
+
Stage -.->|database| Dev
31
+
32
+
style Dev fill:#e1f5ff
33
+
style Stage fill:#fff4e1
34
+
style Prod fill:#e8f5e9
35
+
```
36
+
37
+
-**Development** - Latest development code, not yet released. May be unstable, but CI tests should pass.
38
+
-**Stage** - Pre-production environment. Mirrors production as closely as possible. Used for final release testing.
39
+
-**Production** - Live customer-facing application. Stable and reliable. Source of truth for data.
40
+
41
+
:::info Environment Agreement
42
+
The specific environment setup (dev/stage/production) should be agreed upon within your team and documented in your project. Some teams may use additional environments (e.g., UAT, pre-prod) or different naming conventions.
43
+
:::
44
+
45
+
Code goes "up" (from lower to higher environments) while database goes "down" (from higher to lower environments).
46
+
47
+
This means that the production database is the primary source of truth - it's what code is applied to. When performing a release, you are applying a new version of code to a database within a specific environment.
48
+
49
+
To ensure that code changes work correctly with real data structures, the following process is followed in lower environments:
50
+
1. Database is copied from a higher environment to a lower one (e.g., production → stage → development)
51
+
2. Code is deployed to that environment to be tested against the copied database
52
+
3. Testing is performed to ensure everything works correctly
53
+
54
+
:::tip
55
+
CI pipelines also use a copy of the production database (refreshed daily) to run all tests, ensuring code changes work with real data structures.
56
+
:::
57
+
58
+
You would use a Versioning Workflow (like GitFlow) to manage how code moves
59
+
across releases using the Version Scheme (like CalVer or SemVer).
60
+
61
+
You would document your release procedures in Release Documentation (like
62
+
`docs/releasing.md`) and create a release runsheet to guide release managers
63
+
through the release process.
64
+
65
+
Finally, the actual deployment to production is handled via Automated Deployment
66
+
where, based on your hosting provider, the deployment process is fully automated.
67
+
68
+
## GitFlow Versioning Workflow
69
+
70
+
[git-flow](https://nvie.com/posts/a-successful-git-branching-model/) is a
71
+
versioning workflow that allows you to maintain clean separation between development
72
+
and production code.
73
+
74
+
It allows you to have a stable development branch (`develop`) and a production-ready
75
+
branch (`main`), while providing dedicated branches for feature development,
76
+
release preparation, and hotfixes.
77
+
78
+
```mermaid
79
+
gitGraph
80
+
commit id: "Initial"
81
+
branch develop
82
+
checkout develop
83
+
commit id: "Feature work"
84
+
branch feature/new-feature
85
+
checkout feature/new-feature
86
+
commit id: "Feature commits"
87
+
checkout develop
88
+
merge feature/new-feature
89
+
commit id: "More work"
90
+
branch release/1.0.0
91
+
checkout release/1.0.0
92
+
commit id: "Version bump"
93
+
commit id: "Bug fixes"
94
+
checkout main
95
+
merge release/1.0.0 tag: "v1.0.0"
96
+
checkout develop
97
+
merge release/1.0.0
98
+
checkout develop
99
+
commit id: "Continue dev"
100
+
checkout main
101
+
branch hotfix/1.0.1
102
+
checkout hotfix/1.0.1
103
+
commit id: "Critical fix"
104
+
checkout main
105
+
merge hotfix/1.0.1 tag: "v1.0.1"
106
+
checkout develop
107
+
merge hotfix/1.0.1
108
+
```
109
+
110
+
### Branch Structure
111
+
112
+
-**`develop`** - Development branch where features are integrated
113
+
-**`main`** - Production-ready code, always stable and tagged with releases
114
+
-**`feature/*`** - Individual feature development branches
-**`hotfix/*`** - Emergency fixes for production (e.g., `hotfix/25.1.1`)
117
+
118
+
<details>
119
+
<summary>`production` branch</summary>
120
+
121
+
Most hosting providers support deploying specific git tags directly. In this
122
+
case, no separate `production` branch is needed - you simply tag releases on
123
+
`main` and deploy those tags.
124
+
125
+
Some hosting providers (like **Lagoon**) require a git branch to deploy from,
126
+
so tag-based deployments are not supported. In this case, you must create a
127
+
`production` branch and sync code from `main` to `production` after each
128
+
release.
129
+
130
+
While it's possible to automate copying `main` to `production` on tag creation via CI/CD, this automation is **not currently part of Vortex**. If you need this feature, please [open a new issue](https://github.com/drevops/vortex/issues/new) to request it.
131
+
132
+
</details>
133
+
134
+
### Release Operations
135
+
136
+
Below are the typical steps to perform a release using git-flow. See [cheat sheet](https://danielkummer.github.io/git-flow-cheatsheet/) for a quick reference on git-flow commands.
137
+
138
+
1.**Start Release**
139
+
```bash
140
+
git flow release start X.Y.Z
141
+
```
142
+
Creates a `release/X.Y.Z` branch from `develop`. It is recommended to push
143
+
the branch to remote.
144
+
145
+
2.**Release Preparation**
146
+
- Final bug fixes
147
+
- Documentation updates
148
+
- Release notes preparation
149
+
150
+
3.**Finish Release**
151
+
```bash
152
+
git flow release finish X.Y.Z
153
+
```
154
+
- Merges release branch to `main`
155
+
- Tags the release
156
+
- Merges back to `develop`
157
+
- Deletes the release branch
158
+
159
+
4.**Deploy to Production**
160
+
-**Tag-based hosting:** Deploy the tag directly
161
+
-**Branch-based hosting (e.g., Lagoon):** Manually sync to `production` branch
162
+
```bash
163
+
git push origin main:production
164
+
```
165
+
166
+
#### Expected Release Outcome
167
+
168
+
A successful release should meet these criteria:
169
+
170
+
1. Release branch exists as `release/X.Y.Z` in GitHub repository
171
+
2. Release tag exists as `X.Y.Z` in GitHub repository
172
+
3. The `HEAD` of the `main` branch has `X.Y.Z` tag
173
+
4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch
174
+
- This ensures everything pushed to `main` exists in `develop`
175
+
- Important if `main` had any hotfixes not yet merged to `develop`
176
+
5. There are no open PRs in GitHub related to the release
177
+
178
+
## Version Scheme
179
+
180
+
**Vortex** supports [CalVer](https://calver.org/) and [SemVer](https://semver.org/) version numbering schemes to fit different project needs.
181
+
182
+
During installation, you can choose between Calendar Versioning (CalVer), Semantic Versioning (SemVer), or a custom scheme.
183
+
184
+
### Calendar Versioning (CalVer)
185
+
186
+
**Format:**`YY.M.Z` (e.g., `25.1.0`, `25.11.1`)
187
+
188
+
-`YY` = Short year (no leading zeroes)
189
+
-`M` = Short month (no leading zeroes)
190
+
-`Z` = Hotfix/patch version (no leading zeroes)
191
+
192
+
#### Why CalVer
193
+
-**Release frequency transparency**: When you have multiple releases per month, dates make it easy to identify when a release happened
194
+
-**Intuitive tracking**: Stakeholders can immediately understand "this is from January 2025" vs memorizing version numbers
195
+
-**Natural progression**: No ambiguity about major vs minor changes - just the chronological order
196
+
-**Marketing alignment**: Easier to communicate to non-technical audiences ("our Q1 2025 release")
- ❌ Incorrect: `25.0.0` (no month 0), `2025.1.1` (full year), `25.01.0` (leading zero), `01.1.0` (leading zero in year)
201
+
202
+
Learn more: [CalVer.org](https://calver.org/)
203
+
204
+
### Semantic Versioning (SemVer)
205
+
206
+
**Format:**`X.Y.Z` (e.g., `1.0.0`, `2.3.5`)
207
+
208
+
-`X` = Major release version (no leading zeroes)
209
+
-`Y` = Minor release version (no leading zeroes)
210
+
-`Z` = Hotfix/patch version (no leading zeroes)
211
+
212
+
#### Why SemVer
213
+
-**Breaking change communication**: Major version bump signals incompatible API changes
214
+
-**Dependency management**: Package managers can enforce compatible version ranges
215
+
-**Developer expectations**: Well-understood convention in the development community
216
+
-**Predictable upgrades**: Minor versions add functionality, patches fix bugs
217
+
218
+
#### Examples:
219
+
- ✅ Correct: `0.1.0`, `1.0.0`, `1.0.1`, `1.0.10`
220
+
- ❌ Incorrect: `0.1` (missing patch), `1` (missing minor and patch), `1.0.01` (leading zero)
221
+
222
+
Learn more: [SemVer.org](https://semver.org/)
223
+
224
+
### Other
225
+
226
+
Choose "Other" if you have a custom versioning scheme or don't want to commit to CalVer or SemVer. This option removes both versioning templates from your documentation, allowing you to define your own approach.
227
+
228
+
### Configuration
229
+
230
+
Your project's version scheme is configured once during installation and stored in `.env`:
231
+
232
+
```bash
233
+
VORTEX_RELEASE_VERSION_SCHEME=calver # or semver, or other
234
+
```
235
+
236
+
#### Release Notes Publishing
237
+
238
+
For CalVer and SemVer projects, **Vortex** provides a GitHub Actions workflow to automate release notes drafting:
239
+
240
+
-**Draft release notes** are automatically updated when commits are pushed to the `develop` branch
241
+
- Next version is calculated based on your version scheme
242
+
- Release notes accumulate changes until the release is finalized
243
+
- On release finish, you can use the draft to publish the final release notes
244
+
245
+
## Production Deployment Process
246
+
247
+
Once code is finalized and pushed, the deployment process to production is technically identical to deploying to other environments and is **fully automated**.
248
+
249
+
For Acquia and Lagoon hosting, **Vortex** integrates directly with their deployment systems to ensure smooth releases.
250
+
251
+
For other hosting providers, you can integrate the provision steps into your hosting deployment configuration if it supports post-deployment hooks or custom scripts.
252
+
253
+
See [Provisioning documentation](/docs/drupal/provision#provisioning-flow) to learn more about what provisioning steps are performed during deployments.
254
+
255
+
## Documentation
256
+
257
+
### `docs/releasing.md`
258
+
259
+
Your project includes a `docs/releasing.md` file that serves as the canonical release documentation for your team. This file contains:
260
+
261
+
-**Version scheme summary** - Which versioning system your project uses (CalVer, SemVer, or Other)
262
+
-**GitFlow instructions** - Step-by-step guide for your specific git-flow setup
263
+
-**Release procedures** - Custom workflows specific to your project
264
+
265
+
You can extend this file with:
266
+
-**Detailed release procedures** - A comprehensive outline of _what_ actions to take during releases:
267
+
- Steps to create and finish releases
268
+
- Steps to deploy to production
269
+
- Steps to rollback
270
+
- Steps to verify releases
271
+
-**Release run template** - A detailed checklist of _who_ does _what_ and _when_ during releases. This would be cloned into a separate runsheet for each release.
272
+
273
+
## Monitoring
274
+
275
+
### New Relic Integration
276
+
277
+
**Vortex** provides integration with New Relic for release tracking and monitoring.
278
+
279
+
**Deployment Markers**: When configured, **Vortex** automatically creates deployment markers in New Relic when releases are deployed to your environments. These markers help correlate performance changes, errors, and other metrics with specific releases.
280
+
281
+
**Benefits**:
282
+
- Visualize before/after release performance
283
+
- Correlate errors with specific deployments
284
+
- Track deployment frequency
285
+
- Monitor release impact in real-time
286
+
287
+
See the [Notifications documentation](/docs/workflows/notifications#new-relic) for configuration details.
288
+
289
+
## Best Practices
290
+
291
+
1.**Always use release branches** - Never release directly from `develop` or feature branches
292
+
2.**Backup before release** - Ensure you have recent backups of code and data
293
+
3.**Document your process** - Keep `docs/releasing.md` updated with team conventions
0 commit comments