# Cinc Workstation Long-Term Maintenance Plan

## Background

Chef Workstation has [transitioned to Habitat-only builds](https://github.com/chef/chef-workstation) as part of Progress Chef's shift toward Chef 360. The upstream omnibus build infrastructure is no longer maintained. The Cinc Project rebuilds Chef Workstation as **Cinc Workstation** — a community-maintained, trademark-free distribution using Omnibus packaging.

This document outlines the plan for independent maintenance of Cinc Workstation as a proper fork, replacing the previous rebase-on-upstream workflow.

## Current State

### Architecture

| Component | Language | Description |
|---|---|---|
| `main-cinc-wrapper` | Go | Top-level `cinc` CLI dispatcher |
| `components/gems` | Ruby | All CLI tools bundled via Gemfile |
| `omnibus/` | Ruby | Omnibus project definition and build config |
| `cinc-wrapper` | Bash | `chef-*` → `cinc-*` command redirection |
| `chef-automate-collect` | Go | Automate data collection (currently disabled) |

### Codebase Metrics

- ~150 Ruby gems bundled (chef, inspec, knife, test-kitchen, etc.)
- 10+ omnibus software definitions
- Go CLI wrapper with cross-platform build support
- Build targets: 23 platform variants (Linux x86_64, macOS x86_64/aarch64, Windows x64)

### Current Workflow

As of April 2026, the consolidated `cinc-workstation` repository (`gitlab.com/cinc-project/distribution/cinc-workstation`) is the official independent fork. Source code, build scripts, CI configuration, and integration tests all live in a single repo on the `main` branch. The old `upstream/chef-workstation` repo (with the `stable/cinc` rebase workflow) is retired.

### Cinc Patches (on top of upstream)

- Branding: `cinc-workstation`, `/opt/cinc-workstation` paths, Cinc logos
- Omnibus: `cinc-workstation.rb` project definition, S3 cache at `s3.osuosl.org`
- Gem sources: Cinc-branded gems from `rubygems.cinc.sh` (chef, knife, inspec, etc.)
- Go wrapper: `cinc` binary with Cinc branding from `cinc.sh/assets/cinc-branding-dist.json`
- CLI wrapper: `chef-*` → `cinc-*` command redirection via cinc-wrapper script
- License attribution corrections
---

## Phase 1: Initial Fork Consolidation (April 2026)

### 1.1 Repository Migration

- [x] Create `cinc-workstation` repo from `stable/cinc` branch as `main`
- [x] Absorb build scripts from `workstation/` repo (`build/`, `ci/`, `scripts/`)
- [x] Remove Expeditor automation (`.expeditor/`)
- [x] Remove Habitat build (`habitat/plan.sh`)
- [x] Set up GitLab CI pipeline matching cinc-server patterns
- [x] Add upstream remote for cherry-pick tracking

### 1.1a Legacy Cleanup (April 2026)

- [x] Remove `chef_deprecations` gem (foodcritic/stove/delivery deprecation stubs)
- [x] Remove `foodcritic` and `delivery` appbundle lines from omnibus gems.rb
- [x] Replace `hab` (Chef Habitat) binary with `bio` (Biome) in postinst/postrm/verify
- [x] Remove hab takeover logic from postinst (no longer shipping hab)
- [x] Add optional MR CI jobs for Windows and macOS 26 Intel builds

### 1.2 Dependency Modernization

- [x] Ruby 3.4 upgrade (omnibus_overrides.rb updated to 3.4.9)
- [x] Remove unnecessary dependency overrides (let omnibus-software manage defaults)
- [x] Update Bundler to Ruby 3.4's bundled version
- [x] Verify all gem native extensions compile against Ruby 3.4
- [x] Test nokogiri without upper version pin (Ruby 3.4 supports 1.19.1+)
- [x] Bump Chef to 19.x, InSpec to 7.x, Knife to 19.x
- [x] Remove chef-apply gem (no longer maintained)
- [x] Remove rdoc pin (no longer needed with Ruby 3.4)
- [x] Unpin pry (pry-byebug compatibility resolved)
- [x] Switch from chefstyle to cookstyle for linting
- [x] Consolidate software definitions into omnibus-software gem

### 1.3 Build Validation

- [x] Successful omnibus build on Linux x86_64 (26.0.0-1 deb built)
- [ ] Successful build on macOS (x86_64 + aarch64)
- [ ] Successful build on Windows
- [ ] Integration tests passing on all platforms
- [ ] Docker image build and publish working

---

## Phase 2: Ongoing Maintenance (Q2 2026+)

### 2.1 Upstream Tracking

Since we want close tracking of upstream Chef Workstation changes:

1. **Upstream remote**: `https://github.com/chef/chef-workstation.git` added to repo
2. **Monitoring**: Weekly review of upstream commits for:
   - Security fixes
   - Gem version bumps
   - New kitchen/knife plugins
   - Go wrapper changes
   - Bug fixes
3. **Integration**: Cherry-pick relevant changes (never rebase)
4. **Documentation**: Tag cherry-picked commits with upstream reference

### 2.2 Dependency Update Strategy

#### Security Priority

| Component | Update Frequency | Notes |
|---|---|---|
| OpenSSL | Immediate on CVE | FIPS mode requires 3.2.0+ |
| Ruby | Quarterly | Track latest 3.4.x patch releases |
| Nokogiri | Immediate on CVE | Native extension, platform-sensitive |
| Go | Quarterly | For main-cinc-wrapper builds |
| Chef/InSpec gems | Follow upstream | Via rubygems.cinc.sh |

#### Gem Updates

- Cinc-branded gems (chef, knife, inspec, etc.) are published to `rubygems.cinc.sh`
- Update `components/gems/Gemfile` when new versions are available
- Run `bundle lock --update` to refresh lockfile
- Test gem compilation on all platforms before merge

#### omnibus-software Updates

- Published gem at `rubygems.cinc.sh` from `gitlab.com/cinc-project/distribution/omnibus-software`
- Contains software definitions for Ruby, OpenSSL, Go, git, curl, etc.
- Update by publishing new gem version and running a test build

### 2.3 Platform Support

#### Current Platforms

**Linux x86_64:**
- Amazon Linux 2023
- CentOS/Alma 8, 9, 10
- Debian 12, 13
- Rocky Linux 8, 9, 10
- Ubuntu 20.04, 22.04, 24.04

**macOS:**
- macOS 13, 14, 15, 26 (x86_64 + aarch64)

**Windows:**
- Windows Server 2016 (x64)

#### Platform Lifecycle

- **Add** new platform versions as they release (Ubuntu 26.04, Debian 14, macOS 27, etc.)
- **Drop** EOL platforms after 6 months grace period
- **Test** new platforms in MR pipeline before adding to release builds

### 2.4 Version Management

- Version file: `VERSION` in repo root
- Automated version bump via GitLab CI (label-driven):
  - `version::patch` — default, bump patch
  - `version::minor` — bump minor, reset patch
  - `version::major` — bump major, reset minor and patch
- Tags created automatically on version bump

---

## Phase 3: Long-Term Sustainability

### 3.1 What We Maintain

- **Omnibus packaging** for all supported platforms
- **Security updates** for bundled dependencies
- **Platform support** for current OS versions
- **Cinc branding** consistency
- **Docker images** for containerized usage
- **Test infrastructure** for build validation

### 3.2 What We Do NOT Do

- Major feature development (follow upstream if active)
- Chef 360 integration
- Chef Habitat packaging (replaced by Biome)
- Chef Workstation App (GUI)
- Chef branding compatibility
- Legacy tool stubs (foodcritic, delivery, stove)

### 3.3 Community Contributions

- Contributions welcome via GitLab merge requests
- Follow existing code patterns and conventions
- All commits must be signed off (DCO compliance)
- CI must pass before merge

---

## CI/CD Pipeline

### Pipeline Architecture

```
Stages: lint → package → test → cleanup → deploy → publish

MR Pipeline:
  lint (auto) → multi-platform build+test (manual, optional)
  Available: Linux (Debian 13), macOS 15 aarch64, macOS 26 x86_64, Windows 2016

Release Pipeline (web trigger):
  lint → all platforms build → all platforms test → deploy (manual) → publish

Upstream Trigger:
  lint → all platforms build → all platforms test
```

### Infrastructure

| Component | Provider |
|---|---|
| Linux builds | OSUOSL Docker runners (docker-x86_64) |
| macOS builds | Self-hosted runners (macos-{13,14,15,26}[-aarch64]) |
| Windows builds | Self-hosted runner (windows-2016) |
| S3 cache | OSUOSL (s3.osuosl.org/cinc-omnibus-cache) |
| Package mirror | OSUOSL (ftp-osl.osuosl.org) |
| Gem mirror | rubygems.cinc.sh |
| Docker images | Docker Hub (cincproject/workstation) |

### Build Images

- `cincproject/omnibus-debian:{12,13}`
- `cincproject/omnibus-amazonlinux:2023`
- `cincproject/omnibus-almalinux:{8,9,10}`
- `cincproject/omnibus-rockylinux:{8,9,10}`
- `cincproject/omnibus-ubuntu:{20.04,22.04,24.04}`
- `cincproject/docker-auditor` (source tarball validation)

---

## Risk Assessment

| Risk | Impact | Likelihood | Mitigation |
|---|---|---|---|
| Upstream removes omnibus support entirely | Low | Already happened | We maintain our own omnibus config |
| Ruby gem incompatibility with 3.4 | Medium | Medium | Test compilation early, pin problematic gems |
| Cinc gem mirror unavailability | High | Low | Cache gems in S3, multiple mirror sources |
| macOS/Windows runner unavailability | Medium | Low | Cross-compile where possible, skip platform temporarily |
| omnibus-software gem drift | Medium | Medium | Automated CI job to test new versions |
| Native extension build failures | Medium | Medium | Pin known-good versions, test on all platforms |

---

## References

- [Cinc Project](https://cinc.sh/)
- [Cinc Workstation GitLab](https://gitlab.com/cinc-project/distribution/cinc-workstation)
- [Cinc omnibus-software](https://gitlab.com/cinc-project/distribution/omnibus-software)
- [Upstream Chef Workstation](https://github.com/chef/chef-workstation)
- [OSUOSL](https://osuosl.org/) — Infrastructure sponsor
