Skip to content

Commit 2482bd5

Browse files
porkchopporkchop
committed
versioning system
1 parent 0756dc8 commit 2482bd5

17 files changed

+632
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2026-01-02
9+
10+
### Added
11+
- Initial public release
12+
- Multi-machine conversation sync via git
13+
- Optional transparent encryption with git-crypt
14+
- Backup and restore system with auto-cleanup
15+
- Three-layer configuration system (env vars > local config > shared config)
16+
- Separate initialization workflow (`claude-sync-init`)
17+
- Encryption lock detection and validation
18+
- Project migration utility (`claude-migrate-project`)
19+
- Comprehensive documentation for Linux, macOS, and Windows WSL
20+
- Platform-specific git-crypt installation instructions
21+
- Detailed troubleshooting guide
22+
- Support for GitHub, Bitbucket, GitLab, and any git provider
23+
24+
### Commands
25+
- `claude-sync-init` - Initialize/clone conversations repository
26+
- `claude-sync-push` - Sync local conversations to remote
27+
- `claude-sync-pull` - Pull remote conversations to local
28+
- `claude-sync-status` - Show configuration and sync status
29+
- `claude-backup` - Create timestamped backup
30+
- `claude-backup-list` - List available backups
31+
- `claude-restore` - Restore from backup
32+
- `claude-config` - Interactive configuration wizard
33+
- `claude-enable-encryption` - Enable git-crypt encryption
34+
- `claude-restore-encryption-key` - Restore encryption key
35+
- `claude-migrate-project` - Migrate project conversation paths
36+
37+
### Configuration
38+
- `CLAUDE_SYNC_REMOTE` - Git remote URL
39+
- `CLAUDE_SYNC_BRANCH` - Git branch (default: main)
40+
- `CLAUDE_SYNC_ENCRYPTION` - Enable encryption (default: false)
41+
- `CLAUDE_BACKUP_RETENTION_DAYS` - Backup retention (default: 30)
42+
- `CLAUDE_DATA_DIR` - Claude data directory (default: ~/.claude)
43+
- `CLAUDE_SYNC_VERBOSE` - Verbose output (default: false)
44+
- `CLAUDE_SYNC_COMMIT_MSG` - Commit message template
45+
46+
### Security
47+
- Private repository recommendation
48+
- Optional git-crypt encryption
49+
- Encryption key storage in password managers
50+
- Automatic exclusion of credentials files
51+
52+
[1.0.0]: https://github.com/porkchop/claude-code-sync/releases/tag/v1.0.0

‎CONTRIBUTING.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# Contributing to Claude Code Sync
2+
3+
Thank you for your interest in contributing to Claude Code Sync! This document provides guidelines for contributing to the project.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/claude-code-sync.git`
9+
3. Create a feature branch: `git checkout -b feature/your-feature-name`
10+
4. Make your changes
11+
5. Test your changes thoroughly
12+
6. Submit a pull request
13+
14+
## Development Guidelines
15+
16+
### Code Style
17+
18+
- Follow existing bash script conventions
19+
- Use `set -e` for error handling
20+
- Always save and restore `ORIGINAL_DIR` in scripts
21+
- Use configuration variables from `lib-claude-sync.sh` (never hardcode paths)
22+
- Add helpful error messages with next steps
23+
- Include `--version` support in new commands
24+
25+
### Testing
26+
27+
Before submitting a PR, test on:
28+
- Fresh install (no `~/.claude` exists)
29+
- Existing conversations (merge scenario)
30+
- With encryption enabled
31+
- With non-standard `CLAUDE_DATA_DIR`
32+
33+
### Adding New Features
34+
35+
When adding new commands:
36+
1. Source `lib-claude-sync.sh` for configuration
37+
2. Add `--version` flag support (check existing commands for pattern)
38+
3. Save/restore `ORIGINAL_DIR` (return user to starting directory)
39+
4. Use `$CLAUDE_DATA_DIR` instead of hardcoded `~/.claude`
40+
5. Make script executable: `chmod +x claude-new-command`
41+
6. Update `README.md` with command documentation
42+
7. Update `CLAUDE.md` with development notes
43+
8. Update `CHANGELOG.md` with changes
44+
45+
### Configuration Variables
46+
47+
Always use these variables from config:
48+
- `$CLAUDE_DATA_DIR` - Claude's data directory
49+
- `$CLAUDE_SYNC_REMOTE` - Git remote URL
50+
- `$CLAUDE_SYNC_BRANCH` - Git branch
51+
- `$CLAUDE_SYNC_ENCRYPTION` - Encryption enabled?
52+
- `$CLAUDE_BACKUP_RETENTION_DAYS` - Backup retention
53+
- `$CLAUDE_SYNC_VERBOSE` - Verbose output
54+
55+
### Documentation
56+
57+
- Update `README.md` for user-facing changes
58+
- Update `CLAUDE.md` for development context
59+
- Update `CHANGELOG.md` for all changes
60+
- Include examples in documentation
61+
62+
## Release Process
63+
64+
This project uses [Semantic Versioning](https://semver.org/) (SemVer):
65+
- **MAJOR**: Breaking changes (incompatible API changes, config format changes)
66+
- **MINOR**: New features (backwards compatible)
67+
- **PATCH**: Bug fixes and small improvements
68+
69+
### Creating a Release
70+
71+
We provide a helper script to streamline the release process:
72+
73+
#### 1. Ensure Clean Working Tree
74+
75+
```bash
76+
git status
77+
# Commit any pending changes first
78+
```
79+
80+
#### 2. Run Release Helper
81+
82+
For patch release (bug fixes):
83+
```bash
84+
./claude-release patch
85+
```
86+
87+
For minor release (new features):
88+
```bash
89+
./claude-release minor
90+
```
91+
92+
For major release (breaking changes):
93+
```bash
94+
./claude-release major
95+
```
96+
97+
Or specify exact version:
98+
```bash
99+
./claude-release 1.2.3
100+
```
101+
102+
#### 3. What the Script Does
103+
104+
The `claude-release` script will:
105+
1. Read current version from `VERSION` file
106+
2. Calculate or use the new version number
107+
3. Update `VERSION` file
108+
4. Add new section to `CHANGELOG.md`
109+
5. Prompt you to edit the changelog
110+
6. Create a git commit: `Release vX.Y.Z`
111+
7. Create a git tag: `vX.Y.Z`
112+
113+
#### 4. Update CHANGELOG.md
114+
115+
Edit `CHANGELOG.md` to document changes in the new release:
116+
117+
```markdown
118+
## [1.2.0] - 2026-01-15
119+
120+
### Added
121+
- New feature X that does Y
122+
- Support for platform Z
123+
124+
### Changed
125+
- Improved performance of sync operation
126+
- Updated documentation for clarity
127+
128+
### Fixed
129+
- Fixed bug where X would fail when Y
130+
- Corrected typo in error message
131+
```
132+
133+
#### 5. Push to Remote
134+
135+
```bash
136+
# Push commits and tags
137+
git push origin master --tags
138+
```
139+
140+
#### 6. Create GitHub Release (Optional)
141+
142+
Using GitHub CLI:
143+
```bash
144+
gh release create v1.2.0 \
145+
--title "Version 1.2.0" \
146+
--notes-file CHANGELOG.md
147+
```
148+
149+
Or manually on GitHub:
150+
1. Go to https://github.com/porkchop/claude-code-sync/releases/new
151+
2. Select the tag you just created
152+
3. Copy the changelog section for this version
153+
4. Publish release
154+
155+
### Manual Release (Without Helper Script)
156+
157+
If you prefer to release manually:
158+
159+
1. **Update VERSION file:**
160+
```bash
161+
echo "1.2.0" > VERSION
162+
```
163+
164+
2. **Update CHANGELOG.md:**
165+
Add new section at the top with today's date and changes
166+
167+
3. **Commit changes:**
168+
```bash
169+
git add VERSION CHANGELOG.md
170+
git commit -m "Release v1.2.0"
171+
```
172+
173+
4. **Create tag:**
174+
```bash
175+
git tag -a v1.2.0 -m "Version 1.2.0"
176+
```
177+
178+
5. **Push:**
179+
```bash
180+
git push origin master --tags
181+
```
182+
183+
## Version Numbering Examples
184+
185+
- `1.0.0` → `1.0.1` (patch): Bug fix in backup script
186+
- `1.0.0` → `1.1.0` (minor): Added new command `claude-migrate-project`
187+
- `1.0.0` → `2.0.0` (major): Changed config file format (breaking change)
188+
189+
## Testing Releases
190+
191+
Before releasing:
192+
193+
1. **Test on clean system:**
194+
```bash
195+
# Remove existing setup
196+
rm -rf ~/.claude-sync-test
197+
# Test fresh installation
198+
```
199+
200+
2. **Test version flag:**
201+
```bash
202+
./claude-sync-push --version
203+
./claude-backup --version
204+
# Should show new version
205+
```
206+
207+
3. **Test existing workflows:**
208+
- Fresh setup
209+
- Sync with encryption
210+
- Backup and restore
211+
- Multi-machine sync
212+
213+
## Pull Request Guidelines
214+
215+
### PR Title
216+
217+
Use conventional commit format:
218+
- `feat: add support for Windows WSL`
219+
- `fix: correct tar exclusion for custom data dir`
220+
- `docs: update configuration examples`
221+
- `refactor: simplify encryption key handling`
222+
223+
### PR Description
224+
225+
Include:
226+
- What: Brief description of changes
227+
- Why: Reason for the change
228+
- How: How you implemented it
229+
- Testing: How you tested it
230+
231+
### Example PR Description
232+
233+
```markdown
234+
## What
235+
Adds support for Windows WSL platform.
236+
237+
## Why
238+
Many users run Claude Code in WSL and want to sync conversations.
239+
240+
## How
241+
- Added WSL detection in configuration
242+
- Updated documentation with WSL-specific instructions
243+
- Added git-crypt installation for Ubuntu on WSL
244+
245+
## Testing
246+
- Tested on WSL 2 with Ubuntu 20.04
247+
- Verified sync works between WSL and native Linux
248+
- Tested encryption key restoration
249+
```
250+
251+
## Code Review
252+
253+
All PRs require:
254+
- No breaking changes (unless major version bump)
255+
- Tests pass (manual testing currently)
256+
- Documentation updated
257+
- Code follows existing style
258+
- Scripts return to original directory
259+
- Helpful error messages
260+
261+
## Questions?
262+
263+
- Open an issue: https://github.com/porkchop/claude-code-sync/issues
264+
- Read the docs: https://github.com/porkchop/claude-code-sync#readme
265+
- Check CLAUDE.md for development context
266+
267+
## License
268+
269+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎README.md‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,8 @@ See [SECURITY.md](SECURITY.md) for full security analysis and encryption guide.
297297

298298
## Commands Reference
299299

300+
All commands support `--version` or `-v` to display version information.
301+
300302
### Setup Commands
301303
- `claude-config` - Interactive configuration wizard
302304
- `claude-sync-init` - Initialize/clone the conversations repository
@@ -426,14 +428,40 @@ sudo apt update
426428
sudo apt install git-crypt
427429
```
428430

431+
## Versioning
432+
433+
This project uses [Semantic Versioning](https://semver.org/). Check the version of any command:
434+
435+
```bash
436+
claude-sync-push --version
437+
claude-backup --version
438+
# etc.
439+
```
440+
441+
See [CHANGELOG.md](CHANGELOG.md) for release history.
442+
429443
## Contributing
430444

431-
Contributions welcome! Please:
445+
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
446+
447+
Quick summary:
432448
- Follow existing code style
449+
- Add `--version` support to new commands
433450
- Update documentation
434451
- Test on fresh install
435452
- Ensure scripts return to original directory
436453

454+
### For Maintainers
455+
456+
Release process:
457+
```bash
458+
./claude-release patch # or minor, major
459+
# Edit CHANGELOG.md with release notes
460+
# Push: git push origin master --tags
461+
```
462+
463+
See [CONTRIBUTING.md](CONTRIBUTING.md) for full release documentation.
464+
437465
## License
438466

439467
MIT License - see LICENSE file

‎VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.0.0

‎claude-backup‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
1111

1212
# Load configuration
1313
source "$SCRIPT_DIR/lib-claude-sync.sh"
14+
15+
# Handle --version flag
16+
if [ "$1" = "--version" ] || [ "$1" = "-v" ]; then
17+
show_version "$SCRIPT_DIR" "claude-backup"
18+
exit 0
19+
fi
20+
1421
load_config "$SCRIPT_DIR"
1522

1623
CLAUDE_DIR="$CLAUDE_DATA_DIR"

0 commit comments

Comments
 (0)