Skip to content

Commit a3ce659

Browse files
jdrhynejdrhyne
committed
docs: add manual GitHub issue creation guide
- Created comprehensive guide for manual issue creation - Includes web interface and CLI options - Documents all 14 enhancement issues with priority levels - Provides implementation phase timeline
1 parent a510ba6 commit a3ce659

28 files changed

+2204
-0
lines changed

‎CREATE_GITHUB_ISSUES_MANUALLY.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Manual GitHub Issue Creation Guide
2+
3+
Since automatic issue creation requires PSPDFKit organization permissions, please follow these steps to manually create the issues:
4+
5+
## Prerequisites
6+
1. Ensure you have write access to the PSPDFKit/nutrient-dws-client-python repository
7+
2. Or request someone with appropriate permissions to create these issues
8+
9+
## Issue Templates Location
10+
All issue templates are in the `github_issues/` directory with the following structure:
11+
- `00_roadmap.md` - Overall enhancement roadmap (create this first)
12+
- `01_multi_language_ocr.md` - Multi-language OCR support
13+
- `02_image_watermark.md` - Image watermark support
14+
- `03_selective_flattening.md` - Selective annotation flattening
15+
- `04_create_redactions.md` - Create redactions method
16+
- `05_import_annotations.md` - Import annotations feature
17+
- `06_extract_pages.md` - Extract page range method
18+
- `07_convert_to_pdfa.md` - PDF/A conversion
19+
- `08_convert_to_images.md` - Image extraction
20+
- `09_extract_content_json.md` - JSON content extraction
21+
- `10_convert_to_office.md` - Office format conversion
22+
- `11_ai_redaction.md` - AI-powered redaction
23+
- `12_digital_signature.md` - Digital signature support
24+
- `13_batch_processing.md` - Batch processing method
25+
26+
## Steps to Create Issues
27+
28+
### Option 1: Using GitHub Web Interface
29+
1. Go to https://github.com/PSPDFKit/nutrient-dws-client-python/issues
30+
2. Click "New issue"
31+
3. For each template file:
32+
- Copy the title from the first line (after the #)
33+
- Copy the entire content into the issue body
34+
- Add the labels listed at the bottom of each template
35+
- Click "Submit new issue"
36+
37+
### Option 2: Using GitHub CLI (if you have permissions)
38+
If you get appropriate permissions, you can run:
39+
40+
```bash
41+
cd /Users/admin/Projects/nutrient-dws-client-python
42+
43+
# Create the roadmap issue first
44+
gh issue create \
45+
--title "Enhancement Roadmap: Comprehensive Feature Plan" \
46+
--body-file github_issues/00_roadmap.md \
47+
--label "roadmap,enhancement,documentation"
48+
49+
# Then create individual feature issues
50+
for i in {01..13}; do
51+
title=$(head -n 1 github_issues/${i}_*.md | sed 's/# //')
52+
labels=$(tail -n 1 github_issues/${i}_*.md | sed 's/- //')
53+
gh issue create \
54+
--title "$title" \
55+
--body-file github_issues/${i}_*.md \
56+
--label "$labels"
57+
done
58+
```
59+
60+
### Option 3: Request Organization Access
61+
1. Contact the PSPDFKit organization administrators
62+
2. Request contributor access to the nutrient-dws-client-python repository
63+
3. Once granted, use the GitHub CLI commands above
64+
65+
## Issue Organization
66+
67+
### Priority Labels
68+
- 🔵 `priority-1`: Enhanced existing methods
69+
- 🟢 `priority-2`: Core missing methods
70+
- 🟡 `priority-3`: Format conversion methods
71+
- 🟠 `priority-4`: Advanced features
72+
73+
### Implementation Phases
74+
- **Phase 1** (1-2 months): Issues 01, 02, 04
75+
- **Phase 2** (2-3 months): Issues 07, 08, 05
76+
- **Phase 3** (3-4 months): Issues 09, 10, 11
77+
- **Phase 4** (4-6 months): Issues 12, 13
78+
79+
## Notes
80+
- Create the roadmap issue (00) first as it provides context for all others
81+
- Each issue is self-contained with implementation details, testing requirements, and examples
82+
- Issues are numbered in suggested implementation order within their priority groups
83+
- All issues follow the same format for consistency

‎CREATE_GITHUB_RELEASE.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Steps to Create GitHub Release for v1.0.1
2+
3+
## 1. Go to Releases Page
4+
Navigate to: https://github.com/PSPDFKit/nutrient-dws-client-python/releases
5+
6+
## 2. Click "Create a new release"
7+
8+
## 3. Fill in the Release Details
9+
10+
**Choose a tag**: Select `v1.0.1` from the dropdown
11+
12+
**Release title**: `v1.0.1 - First Stable Release`
13+
14+
**Release notes**: Copy and paste the content from `RELEASE_NOTES_v1.0.1.md`
15+
16+
**Set as latest release**: ✅ Check this box
17+
18+
## 4. Publish Release
19+
Click "Publish release"
20+
21+
## Note
22+
Since the repository has branch protection rules, we cannot push the README updates directly to main. You may want to:
23+
24+
1. Create a PR for the README badge updates
25+
2. Or update the README badges after the release
26+
27+
The updated README includes:
28+
- PyPI version badge
29+
- Python versions badge
30+
- Downloads counter badge
31+
- Updated coverage badge (94%)

‎LOCAL_PUBLISH_GUIDE.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
# Step-by-Step Guide to Publish nutrient-dws to PyPI
2+
3+
## Prerequisites Check
4+
- [ ] Python 3.8+ installed
5+
- [ ] Package built in `dist/` directory
6+
- [ ] All tests passing (154 tests)
7+
- [ ] CI pipeline green
8+
9+
## Step 1: Create PyPI Accounts (if needed)
10+
11+
### 1.1 Create TestPyPI Account (for testing)
12+
1. Go to https://test.pypi.org/account/register/
13+
2. Fill in the registration form
14+
3. Verify your email
15+
16+
### 1.2 Create PyPI Account (for production)
17+
1. Go to https://pypi.org/account/register/
18+
2. Fill in the registration form
19+
3. Verify your email
20+
21+
## Step 2: Generate API Tokens
22+
23+
### 2.1 TestPyPI Token
24+
1. Log in to https://test.pypi.org/
25+
2. Go to Account Settings → API tokens
26+
3. Click "Add API token"
27+
4. Token name: `nutrient-dws-upload`
28+
5. Scope: "Entire account" (first time only)
29+
6. Copy the token (starts with `pypi-`)
30+
7. Save it securely (you won't see it again!)
31+
32+
### 2.2 PyPI Token
33+
1. Log in to https://pypi.org/
34+
2. Go to Account Settings → API tokens
35+
3. Click "Add API token"
36+
4. Token name: `nutrient-dws-upload`
37+
5. Scope: "Entire account" (first time only)
38+
6. Copy the token (starts with `pypi-`)
39+
7. Save it securely (you won't see it again!)
40+
41+
## Step 3: Install Upload Tools
42+
43+
```bash
44+
# Ensure twine is installed
45+
pip3 install --upgrade twine
46+
47+
# Verify installation
48+
python3 -m twine --version
49+
```
50+
51+
## Step 4: Test Upload to TestPyPI
52+
53+
### 4.1 Upload to TestPyPI
54+
```bash
55+
cd /Users/admin/Projects/nutrient-dws-client-python
56+
57+
# Upload both wheel and source distribution
58+
python3 -m twine upload --repository testpypi dist/* \
59+
--username __token__ \
60+
--password <YOUR_TESTPYPI_TOKEN>
61+
```
62+
63+
Expected output:
64+
```
65+
Uploading distributions to https://test.pypi.org/legacy/
66+
Uploading nutrient_dws-1.0.1-py3-none-any.whl
67+
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.3/17.3 kB
68+
Uploading nutrient_dws-1.0.1.tar.gz
69+
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.9/17.9 kB
70+
```
71+
72+
### 4.2 Verify TestPyPI Upload
73+
1. Visit: https://test.pypi.org/project/nutrient-dws/
74+
2. Check that version 1.0.1 is shown
75+
3. Review the project description
76+
77+
### 4.3 Test Installation from TestPyPI
78+
```bash
79+
# Create a test virtual environment
80+
python3 -m venv test_env
81+
source test_env/bin/activate # On Windows: test_env\Scripts\activate
82+
83+
# Install from TestPyPI
84+
pip install --index-url https://test.pypi.org/simple/ \
85+
--extra-index-url https://pypi.org/simple/ \
86+
nutrient-dws
87+
88+
# Test the import
89+
python -c "from nutrient_dws import NutrientClient; print('✅ Import successful!')"
90+
91+
# Test basic functionality
92+
python -c "
93+
from nutrient_dws import NutrientClient
94+
client = NutrientClient(api_key='test')
95+
print('✅ Client created successfully!')
96+
"
97+
98+
# Deactivate test environment
99+
deactivate
100+
rm -rf test_env
101+
```
102+
103+
## Step 5: Publish to Production PyPI
104+
105+
### 5.1 Final Checks
106+
- [ ] TestPyPI upload successful
107+
- [ ] Test installation works
108+
- [ ] No critical issues found
109+
110+
### 5.2 Upload to PyPI
111+
```bash
112+
cd /Users/admin/Projects/nutrient-dws-client-python
113+
114+
# Upload to production PyPI
115+
python3 -m twine upload dist/* \
116+
--username __token__ \
117+
--password <YOUR_PYPI_TOKEN>
118+
```
119+
120+
Expected output:
121+
```
122+
Uploading distributions to https://upload.pypi.org/legacy/
123+
Uploading nutrient_dws-1.0.1-py3-none-any.whl
124+
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.3/17.3 kB
125+
Uploading nutrient_dws-1.0.1.tar.gz
126+
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.9/17.9 kB
127+
128+
View at:
129+
https://pypi.org/project/nutrient-dws/1.0.1/
130+
```
131+
132+
## Step 6: Verify Production Release
133+
134+
### 6.1 Check PyPI Page
135+
1. Visit: https://pypi.org/project/nutrient-dws/
136+
2. Verify version 1.0.1 is live
137+
3. Check that description renders correctly
138+
4. Verify all metadata is correct
139+
140+
### 6.2 Test Installation from PyPI
141+
```bash
142+
# Create a fresh virtual environment
143+
python3 -m venv prod_test
144+
source prod_test/bin/activate # On Windows: prod_test\Scripts\activate
145+
146+
# Install from PyPI
147+
pip install nutrient-dws
148+
149+
# Verify installation
150+
pip show nutrient-dws
151+
152+
# Test import and basic usage
153+
python -c "
154+
from nutrient_dws import NutrientClient
155+
print('✅ Import successful!')
156+
print(f'Version: {__import__(\"nutrient_dws\").__version__}')
157+
"
158+
159+
# Cleanup
160+
deactivate
161+
rm -rf prod_test
162+
```
163+
164+
## Step 7: Post-Publication Tasks
165+
166+
### 7.1 Create Git Tag
167+
```bash
168+
git tag -a v1.0.1 -m "Release version 1.0.1"
169+
git push origin v1.0.1
170+
```
171+
172+
### 7.2 Create GitHub Release
173+
1. Go to https://github.com/PSPDFKit/nutrient-dws-client-python/releases
174+
2. Click "Create a new release"
175+
3. Choose tag: `v1.0.1`
176+
4. Release title: `v1.0.1`
177+
5. Description:
178+
```markdown
179+
## nutrient-dws v1.0.1
180+
181+
First stable release of the Python client library for Nutrient Document Web Services API.
182+
183+
### Features
184+
- Direct API for simple operations
185+
- Builder API for complex workflows
186+
- Comprehensive error handling
187+
- Full type hints support
188+
- 94% test coverage
189+
190+
### Installation
191+
```bash
192+
pip install nutrient-dws
193+
```
194+
195+
### Documentation
196+
See the [README](https://github.com/PSPDFKit/nutrient-dws-client-python) for usage examples.
197+
```
198+
199+
### 7.3 Update Repository (Optional)
200+
Add PyPI badges to README.md:
201+
```markdown
202+
[![PyPI version](https://badge.fury.io/py/nutrient-dws.svg)](https://pypi.org/project/nutrient-dws/)
203+
[![Python versions](https://img.shields.io/pypi/pyversions/nutrient-dws.svg)](https://pypi.org/project/nutrient-dws/)
204+
```
205+
206+
## Troubleshooting
207+
208+
### "Invalid distribution metadata" Warning
209+
- This warning from twine can be ignored
210+
- It doesn't prevent upload or affect functionality
211+
212+
### Authentication Failed
213+
- Ensure you're using `__token__` as username
214+
- Token must include the `pypi-` prefix
215+
- Check for extra spaces or newlines in token
216+
217+
### Package Already Exists
218+
- You can't re-upload the same version
219+
- Increment version in pyproject.toml and rebuild
220+
221+
### Network/Proxy Issues
222+
```bash
223+
# If behind proxy
224+
export HTTPS_PROXY=http://your-proxy:port
225+
python3 -m twine upload --repository-url https://upload.pypi.org/legacy/ dist/*
226+
```
227+
228+
## Security Notes
229+
- Never commit tokens to git
230+
- Use environment variables for automation:
231+
```bash
232+
export TWINE_USERNAME=__token__
233+
export TWINE_PASSWORD=your-token-here
234+
python3 -m twine upload dist/*
235+
```
236+
- Consider using keyring for token storage:
237+
```bash
238+
pip install keyring
239+
keyring set https://upload.pypi.org/legacy/ __token__
240+
```
241+
242+
## Success Checklist
243+
- [ ] Package visible on PyPI
244+
- [ ] Installation works: `pip install nutrient-dws`
245+
- [ ] Import works: `from nutrient_dws import NutrientClient`
246+
- [ ] Git tag created and pushed
247+
- [ ] GitHub release created
248+
- [ ] Team notified of release
249+
250+
---
251+
**Note**: This guide is for local use only. Do not commit to repository.

0 commit comments

Comments
 (0)