chore: Prepare for public release
Public Release Preparation:
- Added CONTRIBUTING.md with contribution guidelines
- Added SECURITY.md with vulnerability reporting process
- Updated README.md with badges and public repository links
- Cleaned internal references (genericized production examples)
- Updated all repository links to PlusOne/dbbackup
- Updated Docker registry to git.uuxo.net/PlusOne/dbbackup
Documentation:
- Contribution guidelines (code style, PR process, testing)
- Security policy (supported versions, disclosure process)
- Community support (issues, discussions, security contact)
Repository Links Updated:
- All git.uuxo.net/uuxo/dbbackup → git.uuxo.net/PlusOne/dbbackup
- Download links, Docker registry, clone URLs updated
- Issue tracker and documentation links updated
Ready for public release! 🚀
This commit is contained in:
296
CONTRIBUTING.md
Normal file
296
CONTRIBUTING.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# Contributing to dbbackup
|
||||
|
||||
Thank you for your interest in contributing to dbbackup! This document provides guidelines and instructions for contributing.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Be respectful, constructive, and professional in all interactions. We're building enterprise software together.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
**Before submitting a bug report:**
|
||||
- Check existing issues to avoid duplicates
|
||||
- Verify you're using the latest version
|
||||
- Collect relevant information (version, OS, database type, error messages)
|
||||
|
||||
**Bug Report Template:**
|
||||
```
|
||||
**Version:** dbbackup v3.1.0
|
||||
**OS:** Linux/macOS/BSD
|
||||
**Database:** PostgreSQL 14 / MySQL 8.0 / MariaDB 10.6
|
||||
**Command:** The exact command that failed
|
||||
**Error:** Full error message and stack trace
|
||||
**Expected:** What you expected to happen
|
||||
**Actual:** What actually happened
|
||||
```
|
||||
|
||||
### Feature Requests
|
||||
|
||||
We welcome feature requests! Please include:
|
||||
- **Use Case:** Why is this feature needed?
|
||||
- **Description:** What should the feature do?
|
||||
- **Examples:** How would it be used?
|
||||
- **Alternatives:** What workarounds exist today?
|
||||
|
||||
### Pull Requests
|
||||
|
||||
**Before starting work:**
|
||||
1. Open an issue to discuss the change
|
||||
2. Wait for maintainer feedback
|
||||
3. Fork the repository
|
||||
4. Create a feature branch
|
||||
|
||||
**PR Requirements:**
|
||||
- ✅ All tests pass (`go test -v ./...`)
|
||||
- ✅ New tests added for new features
|
||||
- ✅ Documentation updated (README.md, comments)
|
||||
- ✅ Code follows project style
|
||||
- ✅ Commit messages are clear and descriptive
|
||||
- ✅ No breaking changes without discussion
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
```bash
|
||||
# Required
|
||||
- Go 1.21 or later
|
||||
- PostgreSQL 9.5+ (for testing)
|
||||
- MySQL 5.7+ or MariaDB 10.3+ (for testing)
|
||||
- Docker (optional, for integration tests)
|
||||
|
||||
# Install development dependencies
|
||||
go mod download
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
# Build binary
|
||||
go build -o dbbackup
|
||||
|
||||
# Build all platforms
|
||||
./build_all.sh
|
||||
|
||||
# Build Docker image
|
||||
docker build -t dbbackup:dev .
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
go test -v ./...
|
||||
|
||||
# Run specific test suite
|
||||
go test -v ./tests/pitr_complete_test.go
|
||||
|
||||
# Run with coverage
|
||||
go test -cover ./...
|
||||
|
||||
# Run integration tests (requires databases)
|
||||
./run_integration_tests.sh
|
||||
```
|
||||
|
||||
### Code Style
|
||||
|
||||
**Follow Go best practices:**
|
||||
- Use `gofmt` for formatting
|
||||
- Use `go vet` for static analysis
|
||||
- Follow [Effective Go](https://golang.org/doc/effective_go.html)
|
||||
- Write clear, self-documenting code
|
||||
- Add comments for complex logic
|
||||
|
||||
**Project conventions:**
|
||||
- Package names: lowercase, single word
|
||||
- Function names: CamelCase, descriptive
|
||||
- Variables: camelCase, meaningful names
|
||||
- Constants: UPPER_SNAKE_CASE
|
||||
- Errors: Wrap with context using `fmt.Errorf`
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
// Good
|
||||
func BackupDatabase(ctx context.Context, config *Config) error {
|
||||
if err := validateConfig(config); err != nil {
|
||||
return fmt.Errorf("invalid config: %w", err)
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
// Avoid
|
||||
func backup(c *Config) error {
|
||||
// No context, unclear name, no error wrapping
|
||||
}
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
dbbackup/
|
||||
├── cmd/ # CLI commands (Cobra)
|
||||
├── internal/ # Internal packages
|
||||
│ ├── backup/ # Backup engine
|
||||
│ ├── restore/ # Restore engine
|
||||
│ ├── pitr/ # Point-in-Time Recovery
|
||||
│ ├── cloud/ # Cloud storage backends
|
||||
│ ├── crypto/ # Encryption
|
||||
│ └── config/ # Configuration
|
||||
├── tests/ # Test suites
|
||||
├── bin/ # Compiled binaries
|
||||
├── main.go # Entry point
|
||||
└── README.md # Documentation
|
||||
```
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
**Unit Tests:**
|
||||
- Test public APIs
|
||||
- Mock external dependencies
|
||||
- Use table-driven tests
|
||||
- Test error cases
|
||||
|
||||
**Integration Tests:**
|
||||
- Test real database operations
|
||||
- Use Docker containers for isolation
|
||||
- Clean up resources after tests
|
||||
- Test all supported database versions
|
||||
|
||||
**Example Test:**
|
||||
```go
|
||||
func TestBackupRestore(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
dbType string
|
||||
size int64
|
||||
expected error
|
||||
}{
|
||||
{"PostgreSQL small", "postgres", 1024, nil},
|
||||
{"MySQL large", "mysql", 1024*1024, nil},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
// Test implementation
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
**Update documentation when:**
|
||||
- Adding new features
|
||||
- Changing CLI flags
|
||||
- Modifying configuration options
|
||||
- Updating dependencies
|
||||
|
||||
**Documentation locations:**
|
||||
- `README.md` - Main documentation
|
||||
- `PITR.md` - PITR guide
|
||||
- `DOCKER.md` - Docker usage
|
||||
- Code comments - Complex logic
|
||||
- `CHANGELOG.md` - Version history
|
||||
|
||||
## Commit Guidelines
|
||||
|
||||
**Commit Message Format:**
|
||||
```
|
||||
<type>: <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat:` New feature
|
||||
- `fix:` Bug fix
|
||||
- `docs:` Documentation only
|
||||
- `style:` Code style changes (formatting)
|
||||
- `refactor:` Code refactoring
|
||||
- `test:` Adding or updating tests
|
||||
- `chore:` Maintenance tasks
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
feat: Add Azure Blob Storage backend
|
||||
|
||||
Implements Azure Blob Storage backend for cloud backups.
|
||||
Includes streaming upload/download and metadata preservation.
|
||||
|
||||
Closes #42
|
||||
|
||||
---
|
||||
|
||||
fix: Handle MySQL connection timeout gracefully
|
||||
|
||||
Adds retry logic for transient connection failures.
|
||||
Improves error messages for timeout scenarios.
|
||||
|
||||
Fixes #56
|
||||
```
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. **Create Feature Branch**
|
||||
```bash
|
||||
git checkout -b feature/my-feature
|
||||
```
|
||||
|
||||
2. **Make Changes**
|
||||
- Write code
|
||||
- Add tests
|
||||
- Update documentation
|
||||
|
||||
3. **Commit Changes**
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat: Add my feature"
|
||||
```
|
||||
|
||||
4. **Push to Fork**
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
|
||||
5. **Open Pull Request**
|
||||
- Clear title and description
|
||||
- Reference related issues
|
||||
- Wait for review
|
||||
|
||||
6. **Address Feedback**
|
||||
- Make requested changes
|
||||
- Push updates to same branch
|
||||
- Respond to comments
|
||||
|
||||
7. **Merge**
|
||||
- Maintainer will merge when approved
|
||||
- Squash commits if requested
|
||||
|
||||
## Release Process (Maintainers)
|
||||
|
||||
1. Update version in `main.go`
|
||||
2. Update `CHANGELOG.md`
|
||||
3. Create release notes (`RELEASE_NOTES_vX.Y.Z.md`)
|
||||
4. Commit: `git commit -m "Release vX.Y.Z"`
|
||||
5. Tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
|
||||
6. Push: `git push origin main vX.Y.Z`
|
||||
7. Build binaries: `./build_all.sh`
|
||||
8. Create GitHub Release with binaries
|
||||
|
||||
## Questions?
|
||||
|
||||
- **Issues:** https://git.uuxo.net/PlusOne/dbbackup/issues
|
||||
- **Discussions:** Use issue tracker for now
|
||||
- **Email:** See SECURITY.md for contact
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
|
||||
|
||||
---
|
||||
|
||||
**Thank you for contributing to dbbackup!** 🎉
|
||||
Reference in New Issue
Block a user