Skip to content

Commit 8c954cf

Browse files
Satyam-10124Satyam-10124
committed
docs updates
1 parent 06115d1 commit 8c954cf

1 file changed

Lines changed: 178 additions & 97 deletions

File tree

‎.github/PYPI_SETUP.md‎

Lines changed: 178 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,212 @@
1-
# PyPI Publishing Setup via GitHub Actions
1+
# 🚀 PyPI Publishing Setup for Maranda
22

3-
## Information for Maranda/CompliLedger Team
3+
Hi Maranda! This guide will help you publish the CompZ SDK to PyPI so anyone can install it with `pip install compz`.
44

5-
### 1. Repository Link
6-
```
7-
https://github.com/Compliledger/CompZ
8-
```
5+
---
96

10-
### 2. Workflow Name
11-
```
12-
publish-to-pypi
13-
```
14-
(File: `.github/workflows/publish-to-pypi.yml`)
7+
## 📋 Quick Info You Need
158

16-
### 3. GitHub Actions Environment
17-
```
18-
pypi
19-
```
9+
| What | Value |
10+
|------|-------|
11+
| **Repo** | https://github.com/Compliledger/CompZ |
12+
| **Workflow File** | [`.github/workflows/publish-to-pypi.yml`](../workflows/publish-to-pypi.yml) |
13+
| **Environment Name** | `pypi` |
14+
| **Secret Name** | `PYPI_API_TOKEN` |
15+
| **Package Name** | `compz` |
2016

2117
---
2218

23-
## Setup Instructions
24-
25-
### Step 1: Create GitHub Environment
26-
1. Go to: `https://github.com/Compliledger/CompZ/settings/environments`
27-
2. Click "New environment"
28-
3. Name it: `pypi`
29-
4. Click "Configure environment"
30-
5. (Optional) Add protection rules:
31-
- Required reviewers
32-
- Deployment branches (e.g., only `main` or `release/*`)
33-
34-
### Step 2: Add PyPI API Token as Secret
35-
1. Get PyPI token:
36-
- Go to https://pypi.org/manage/account/token/
37-
- Create new token with scope: "Project: compz" OR "Entire account"
38-
- Copy the token (starts with `pypi-...`)
39-
40-
2. Add to GitHub:
41-
- Go to: `https://github.com/Compliledger/CompZ/settings/secrets/actions`
42-
- Click "New repository secret"
43-
- Name: `PYPI_API_TOKEN`
44-
- Value: Paste your PyPI token
45-
- Click "Add secret"
46-
47-
### Step 3: Publishing Options
48-
49-
**Option A: Automatic on Release**
50-
1. Go to: `https://github.com/Compliledger/CompZ/releases`
51-
2. Click "Create a new release"
52-
3. Tag version: `v1.0.0`
53-
4. Release title: `CompZ v1.0.0`
54-
5. Click "Publish release"
55-
6. → GitHub Actions will automatically build and publish to PyPI
56-
57-
**Option B: Manual Trigger**
58-
1. Go to: `https://github.com/Compliledger/CompZ/actions`
59-
2. Select "Publish to PyPI" workflow
60-
3. Click "Run workflow"
61-
4. Select branch (usually `main`)
62-
5. Click "Run workflow"
63-
6. → Builds and publishes immediately
19+
## ✅ Setup Checklist (Do These 3 Things)
20+
21+
### 🔷 Step 1: Get a PyPI Token (2 minutes)
22+
23+
1. **Log into PyPI**: https://pypi.org/account/login/
24+
2. **Go to API tokens**: https://pypi.org/manage/account/token/
25+
3. **Click "Add API token"**
26+
4. **Fill in the form**:
27+
- Token name: `CompZ GitHub Actions`
28+
- Scope: Choose **"Project: compz"** (if it exists) OR **"Entire account"**
29+
5. **Click "Add token"**
30+
6. **IMPORTANT**: Copy the token immediately! It starts with `pypi-...`
31+
- You'll only see it once!
32+
- Save it in a safe place temporarily
33+
34+
**🔗 Direct Link**: https://pypi.org/manage/account/token/
6435

6536
---
6637

67-
## Workflow Features
38+
### 🔷 Step 2: Create GitHub Environment (1 minute)
6839

69-
- ✅ Automated build on release
70-
- ✅ Manual trigger available
71-
- ✅ Package validation before upload
72-
- ✅ Environment protection
73-
- ✅ Secure token management
74-
- ✅ Build artifacts saved
40+
1. **Go to repository settings**: https://github.com/Compliledger/CompZ/settings/environments
41+
2. **Click green "New environment" button** (top right)
42+
3. **Name it exactly**: `pypi` (lowercase, no spaces)
43+
4. **Click "Configure environment"**
44+
5. **Optional but recommended**:
45+
- Under "Deployment branches", select "Selected branches"
46+
- Add rule: `main` (only allows publishing from main branch)
47+
6. **Click "Save protection rules"**
48+
49+
**🔗 Direct Link**: https://github.com/Compliledger/CompZ/settings/environments/new
7550

7651
---
7752

78-
## Current Package Info
53+
### 🔷 Step 3: Add PyPI Token as Secret (1 minute)
7954

80-
- **Package Name**: `compz`
81-
- **Version**: `1.0.0` (from setup.py)
82-
- **Python**: 3.8+
83-
- **CLI Command**: `compz`
55+
1. **Go to secrets page**: https://github.com/Compliledger/CompZ/settings/secrets/actions
56+
2. **Click green "New repository secret" button** (top right)
57+
3. **Fill in**:
58+
- Name: `PYPI_API_TOKEN` (exactly this, all caps)
59+
- Secret: Paste the `pypi-...` token you got in Step 1
60+
4. **Click "Add secret"**
8461

85-
After publishing, users can install with:
86-
```bash
87-
pip install compz
88-
```
62+
**🔗 Direct Link**: https://github.com/Compliledger/CompZ/settings/secrets/actions/new
8963

9064
---
9165

92-
## Testing Before Publishing
66+
## 🎉 Publishing the Package
9367

94-
Test locally first:
95-
```bash
96-
# Clean build
97-
rm -rf build/ dist/ *.egg-info
68+
Once setup is done, you have 2 ways to publish:
69+
70+
### 🅰️ Option A: Create a Release (Recommended)
71+
72+
**This automatically publishes to PyPI when you create a GitHub release.**
73+
74+
1. **Go to releases**: https://github.com/Compliledger/CompZ/releases
75+
2. **Click "Draft a new release"**
76+
3. **Fill in**:
77+
- Click "Choose a tag"
78+
- Type: `v1.0.0` (or whatever version is in `setup.py`)
79+
- Click "Create new tag: v1.0.0 on publish"
80+
- Release title: `CompZ v1.0.0 - Initial Release`
81+
- Description: Add release notes (what's new, features, etc.)
82+
4. **Click green "Publish release" button**
83+
5. **Watch it work**: Go to https://github.com/Compliledger/CompZ/actions
84+
- You'll see "Publish to PyPI" workflow running
85+
- Wait ~2-3 minutes
86+
- ✅ Should show green checkmark when done!
87+
88+
**🔗 Direct Link**: https://github.com/Compliledger/CompZ/releases/new
89+
90+
---
91+
92+
### 🅱️ Option B: Manual Trigger
93+
94+
**This publishes immediately without creating a release.**
95+
96+
1. **Go to Actions tab**: https://github.com/Compliledger/CompZ/actions
97+
2. **Click "Publish to PyPI"** in the left sidebar
98+
3. **Click "Run workflow"** button (right side)
99+
4. **Select branch**: Usually `main`
100+
5. **Click green "Run workflow" button**
101+
6. **Watch it work**: Refresh the page
102+
- You'll see the workflow running
103+
- Wait ~2-3 minutes
104+
- ✅ Should show green checkmark when done!
105+
106+
**🔗 Direct Link**: https://github.com/Compliledger/CompZ/actions/workflows/publish-to-pypi.yml
107+
108+
---
98109

99-
# Build package
100-
python3 -m build
110+
## 🎯 After Publishing
101111

102-
# Check package
103-
twine check dist/*
112+
### Check if it worked:
104113

105-
# Test upload to TestPyPI (optional)
106-
twine upload -r testpypi dist/*
114+
1. **Visit PyPI**: https://pypi.org/project/compz/
115+
- Should show version 1.0.0
116+
- Should show README content
117+
- Should show install command
107118

108-
# Test install from TestPyPI
109-
pip install -i https://test.pypi.org/simple/ compz
119+
2. **Test installation**:
120+
```bash
121+
pip install compz
122+
compz --help
123+
```
124+
125+
3. **Share with users**:
126+
```bash
127+
pip install compz
128+
```
129+
130+
---
131+
132+
## 🐛 Troubleshooting
133+
134+
### ❌ "Invalid API Token" error
135+
**Problem**: Token doesn't have permission for "compz" package.
136+
137+
**Fix**:
138+
1. Go back to https://pypi.org/manage/account/token/
139+
2. Create a NEW token with scope "Entire account" (not project-specific)
140+
3. Update the secret at https://github.com/Compliledger/CompZ/settings/secrets/actions
141+
4. Click on `PYPI_API_TOKEN` → "Update" → Paste new token → "Update secret"
142+
143+
---
144+
145+
### ❌ "Package name already exists" error
146+
**Problem**: Someone else already owns "compz" on PyPI.
147+
148+
**Fix**:
149+
1. Pick a different name like: `compz-sdk`, `compliledger-compz`, `zk-compz`
150+
2. Update `setup.py` line 13: Change `name="compz"` to your new name
151+
3. Commit and push
152+
4. Try publishing again
153+
154+
---
155+
156+
### ❌ "PYPI_API_TOKEN not found" error
157+
**Problem**: Secret wasn't created or has wrong name.
158+
159+
**Fix**:
160+
1. Go to https://github.com/Compliledger/CompZ/settings/secrets/actions
161+
2. Make sure you see `PYPI_API_TOKEN` in the list
162+
3. Name must be EXACTLY `PYPI_API_TOKEN` (all caps, underscores)
163+
4. If wrong, delete it and create new one with correct name
164+
165+
---
166+
167+
### ❌ Workflow doesn't run
168+
**Problem**: Workflow file wasn't pushed to GitHub.
169+
170+
**Fix**:
171+
```bash
172+
# Make sure the workflow file is committed
173+
git add .github/workflows/publish-to-pypi.yml
174+
git commit -m "Add PyPI publishing workflow"
175+
git push
110176
```
111177

112178
---
113179

114-
## Troubleshooting
180+
## 📝 Important Files
115181

116-
**Error: "Invalid API Token"**
117-
- Make sure token scope matches package name
118-
- Use global token if publishing multiple packages
182+
| File | What It Does | Link |
183+
|------|-------------|------|
184+
| `setup.py` | Package configuration (name, version, dependencies) | [View File](../../setup.py) |
185+
| `MANIFEST.in` | Lists what files to include in package | [View File](../../MANIFEST.in) |
186+
| `requirements.txt` | Python dependencies | [View File](../../requirements.txt) |
187+
| `.github/workflows/publish-to-pypi.yml` | Automation workflow | [View File](../workflows/publish-to-pypi.yml) |
119188

120-
**Error: "Package already exists"**
121-
- Bump version in `setup.py`
122-
- PyPI doesn't allow re-uploading same version
189+
---
123190

124-
**Error: "PYPI_API_TOKEN not found"**
125-
- Check secret name is exactly `PYPI_API_TOKEN`
126-
- Check it's added to repository secrets (not environment secrets)
191+
## 🆘 Need Help?
192+
193+
1. **Check workflow run logs**: https://github.com/Compliledger/CompZ/actions
194+
- Click on the failed run
195+
- Click on "build-and-publish" job
196+
- Read the error messages
197+
198+
2. **Contact Satyam** if you're stuck!
199+
200+
3. **PyPI Help**: https://pypi.org/help/
127201

128202
---
129203

130-
## Contact
131-
For issues, contact: support@compliledger.com
204+
## ✨ That's It!
205+
206+
After setup, publishing is just:
207+
1. Create a GitHub release → Done! 🎉
208+
209+
Or:
210+
1. Click "Run workflow" → Done! 🎉
211+
212+
The package will be live at: https://pypi.org/project/compz/

0 commit comments

Comments
 (0)