Skip to content

Commit 0bc2a7a

Browse files
rupeshjSFDCrupeshjSFDC
authored
Feature/package (#1)
* Refractor: Typecheck for ADOService Signed-off-by: Rupesh J <rupesh.j@salesforce.com> * Initial Publish Signed-off-by: Rupesh J <rupesh.j@salesforce.com> * Increment Version Signed-off-by: Rupesh J <rupesh.j@salesforce.com> * Add Plugin info and version check for cli commands Signed-off-by: Rupesh J <rupesh.j@salesforce.com> * Check dependency installation. Signed-off-by: Rupesh J <rupesh.j@salesforce.com> * Add CCI scripts, Bump the version Signed-off-by: Rupesh J <rupesh.j@salesforce.com> * Add Github workflow to publish automatically Signed-off-by: Rupesh J <rupesh.j@salesforce.com> --------- Signed-off-by: Rupesh J <rupesh.j@salesforce.com>
1 parent b7d5dab commit 0bc2a7a

23 files changed

Lines changed: 1966 additions & 103 deletions

‎.github/workflows/feature_test.yml‎

Lines changed: 0 additions & 60 deletions
This file was deleted.

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
- name: Set up Python
1919
uses: actions/setup-python@v4
2020
with:
21-
python-version: "3.11"
21+
python-version: "3.12"
2222
- name: Install build tools
2323
run: pip install hatch
2424
- name: Build package

‎.github/workflows/release_test.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Publish and release cumulusci-plus-azure-devops
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- cumulusci_ado/__about__.py
9+
10+
concurrency: publishing
11+
12+
jobs:
13+
publish-to-pypi:
14+
name: Publish new release to PyPI
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- name: Set up Python
19+
uses: actions/setup-python@v4
20+
with:
21+
python-version: "3.12"
22+
- name: Install build tools
23+
run: pip install hatch
24+
- name: Build package
25+
run: hatch build -c
26+
- name: Publish to PyPI
27+
env:
28+
HATCH_INDEX_USER: "__token__"
29+
HATCH_INDEX_AUTH: ${{ secrets.TEST_PYPI_TOKEN }}
30+
run: hatch publish

‎INSTALLATION.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# CumulusCI Plus Azure DevOps - Installation Guide
2+
3+
## Overview
4+
5+
This guide explains how to properly install `cumulusci-plus-azure-devops` and addresses common concerns about dependency management and potential conflicts.
6+
7+
## Understanding Dependency Installation
8+
9+
### How pipx Handles Dependencies
10+
11+
When you install a package with pipx, it **automatically installs all dependencies** listed in the package's `dependencies` array. This includes:
12+
13+
- `cumulusci-plus>=5.0.0`
14+
- `azure-devops`
15+
- `requests`
16+
- `humanfriendly`
17+
- `distro`
18+
- `packaging>=23.0`
19+
20+
### Why Dependencies Might Seem Missing
21+
22+
If you think dependencies aren't being installed, it might be because:
23+
24+
1. **Isolated Environment**: pipx installs packages in isolated virtual environments, so dependencies aren't visible globally
25+
2. **Network Issues**: Installation failed due to connectivity problems
26+
3. **Package Conflicts**: Conflicting packages prevented proper installation
27+
4. **Outdated pipx**: Using an old version of pipx
28+
29+
## Installation Methods
30+
31+
### Method 1: Recommended Installation (with conflict checking)
32+
33+
Use our custom installation script that performs pre-installation checks:
34+
35+
```bash
36+
# Download and run the installation script
37+
curl -O https://raw.githubusercontent.com/jorgesolebur/CumulusCI_AzureDevOps/main/install.py
38+
python install.py
39+
```
40+
41+
This script will:
42+
43+
- ✅ Check if pipx is available
44+
- ✅ Detect conflicting packages
45+
- ✅ Warn about potential conflicts
46+
- ✅ Guide you through resolution steps
47+
- ✅ Install the package with all dependencies
48+
49+
### Method 2: Direct pipx Installation
50+
51+
```bash
52+
pipx install cumulusci-plus-azure-devops
53+
```
54+
55+
### Method 3: pip Installation (not recommended for CLI tools)
56+
57+
```bash
58+
pip install cumulusci-plus-azure-devops
59+
```
60+
61+
## Upgrading
62+
63+
### pipx Upgrade Limitations
64+
65+
pipx has a known limitation: **it only upgrades the main package, not its dependencies**. This means running `pipx upgrade cumulusci-plus-azure-devops` may not update `cumulusci-plus`, `azure-devops`, or other dependencies to their latest versions.
66+
67+
### Recommended Upgrade Method
68+
69+
Use our custom upgrade script:
70+
71+
```bash
72+
# Download and run the upgrade script
73+
curl -O https://raw.githubusercontent.com/jorgesolebur/CumulusCI_AzureDevOps/main/upgrade.py
74+
python upgrade.py
75+
```
76+
77+
The script will:
78+
79+
- Check current versions of all dependencies
80+
- Offer options for standard upgrade or force reinstall
81+
- Ensure dependencies are updated to latest versions
82+
- Verify successful upgrade
83+
- Provide clear feedback and next steps
84+
85+
### Manual Upgrade Options
86+
87+
```bash
88+
# Option 1: Standard upgrade (main package only)
89+
pipx upgrade cumulusci-plus-azure-devops
90+
91+
# Option 2: Force reinstall (updates dependencies)
92+
pipx uninstall cumulusci-plus-azure-devops
93+
pipx install cumulusci-plus-azure-devops
94+
95+
# Option 3: Check what needs upgrading
96+
python upgrade.py --check-only
97+
```
98+
99+
### Why Force Reinstall is Sometimes Needed
100+
101+
When dependencies have security updates or important bug fixes, you need to force reinstall to get the latest versions. The upgrade script makes this process seamless.
102+
103+
## Conflict Prevention
104+
105+
### The Problem
106+
107+
This package is designed to work with `cumulusci-plus` (the next-generation CumulusCI), not the original `cumulusci` package. Having both installed can cause:
108+
109+
- Import conflicts
110+
- Command name collisions
111+
- Dependency version conflicts
112+
- Unexpected behavior
113+
114+
### Our Solutions
115+
116+
#### 1. Runtime Conflict Detection
117+
118+
The package includes runtime checks that warn users if conflicts are detected:
119+
120+
```python
121+
# This runs automatically when you import the package
122+
WARNING: Both 'cumulusci' and 'cumulusci-plus' packages are detected.
123+
This may cause conflicts. Please use 'cumulusci-plus' instead of 'cumulusci'.
124+
Consider uninstalling 'cumulusci' with: pip uninstall cumulusci
125+
```
126+
127+
#### 2. Pre-installation Checks
128+
129+
Our custom installation script checks for:
130+
131+
- Global installations of conflicting packages
132+
- Existing pipx installations of conflicting packages
133+
- Missing prerequisites
134+
135+
#### 3. Clear Documentation
136+
137+
This guide and the README clearly explain the relationship between packages and recommended installation methods.
138+
139+
## Troubleshooting
140+
141+
### "Dependencies not installed" Error
142+
143+
If you get this error:
144+
145+
1. **Check pipx environment**:
146+
147+
```bash
148+
pipx list
149+
# Should show cumulusci-plus-azure-devops with its dependencies
150+
```
151+
152+
2. **Verify installation**:
153+
154+
```bash
155+
cumulusci-ado status
156+
# Or use the short alias: cci-ado status
157+
```
158+
159+
3. **Reinstall if needed**:
160+
```bash
161+
pipx uninstall cumulusci-plus-azure-devops
162+
pipx install cumulusci-plus-azure-devops
163+
```
164+
165+
### Dependencies Not Upgrading
166+
167+
If dependencies seem outdated after `pipx upgrade`:
168+
169+
1. **Check current versions**:
170+
171+
```bash
172+
python upgrade.py --check-only
173+
```
174+
175+
2. **Force reinstall**:
176+
177+
```bash
178+
python upgrade.py --force-reinstall
179+
# Or manually:
180+
pipx uninstall cumulusci-plus-azure-devops
181+
pipx install cumulusci-plus-azure-devops
182+
```
183+
184+
### Conflict Resolution
185+
186+
If you have conflicting packages:
187+
188+
1. **Remove conflicting packages**:
189+
190+
```bash
191+
# Remove global installation
192+
pip uninstall cumulusci
193+
194+
# Remove pipx installation
195+
pipx uninstall cumulusci
196+
```
197+
198+
2. **Clean reinstall**:
199+
```bash
200+
pipx install cumulusci-plus-azure-devops
201+
```
202+
203+
### Verification
204+
205+
After installation, verify everything works:
206+
207+
```bash
208+
# Check installation
209+
pipx list | grep cumulusci
210+
211+
# Test the CLI commands
212+
cumulusci-ado status
213+
cci-ado version
214+
215+
# Check for conflicts (should show no warnings)
216+
python -c "import cumulusci_ado; print('Installation successful!')"
217+
```
218+
219+
## Technical Details
220+
221+
### Why These Approaches Work
222+
223+
1. **pipx Isolation**: Each package gets its own virtual environment, preventing most conflicts
224+
2. **Runtime Checks**: Early detection of conflicts when they do occur
225+
3. **Clear Dependencies**: Explicit dependency specification in `pyproject.toml`
226+
4. **User Education**: Clear documentation about proper installation methods
227+
228+
### Limitations
229+
230+
- **Cannot prevent installation**: Python packaging standards don't support pre-installation hooks
231+
- **Runtime detection only**: Conflicts are detected after installation, not prevented
232+
- **User cooperation required**: Users must follow recommendations to avoid conflicts
233+
234+
## Best Practices
235+
236+
1. **Use pipx for CLI tools**: Better isolation than pip
237+
2. **Use our installation script**: Includes conflict checking
238+
3. **Keep packages updated**: Regular updates prevent compatibility issues
239+
4. **Follow migration guides**: When switching between package versions
240+
5. **Report issues**: Help us improve conflict detection
241+
242+
## Support
243+
244+
If you encounter issues:
245+
246+
1. Check this guide first
247+
2. Look at the main README.md
248+
3. Open an issue on GitHub with:
249+
- Your operating system
250+
- Python version
251+
- Installation method used
252+
- Error messages
253+
- Output of `pipx list`

0 commit comments

Comments
 (0)