Add versioning guidelines to CLAUDE.md

CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive docstrings for all public methods
+
+### Changed
+- Improved documentation formatting for `order_by` parameters
+
+## [0.1.0] - 2024-02-09
+
+### Added
+- Initial release of Nansen Python SDK
+- Support for all major Nansen API endpoints:
+  - Token God Mode (TGM): token screener, holders, flows, transfers, DCAs, perp screener
+  - Smart Money: netflow, holdings, historical holdings, DEX trades, perp trades, DCAs
+  - Profiler: PnL summary/detailed, perp positions/trades, address balances/transactions/counterparties/labels, entity search, perp leaderboard
+  - Portfolio: DeFi holdings
+  - Points: leaderboard (public, no auth required)
+- Full sync and async support with identical APIs
+- Auto-pagination for all paginated endpoints via `SyncPage`/`AsyncPage`
+- Automatic retry logic with exponential backoff for 429/5xx errors
+- Comprehensive error handling with typed exceptions
+- Rate limit information in all responses
+- Type-safe request/response models using Pydantic v2
+- 35+ runnable example scripts demonstrating all endpoints
+- Full test coverage using pytest and respx mocks
+- CI/CD pipeline with automated testing
+- Pre-commit hooks for code quality
+- Python 3.10+ support
+
+### Development
+- Ruff for linting and formatting
+- Strict mypy type checking
+- Poetry for dependency management
+- httpx for HTTP client (sync + async)
+
+[Unreleased]: https://github.com/nansen-ai/nansen-python-sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nansen-ai/nansen-python-sdk/releases/tag/v0.1.0

CLAUDE.md

@@ -64,3 +64,34 @@ poetry run python examples/try_token_screener.py
 - Ruff for linting/formatting (line length 100)
 - Strict mypy with pydantic plugin
 - Use `timezone.utc` for UTC datetimes (not deprecated `datetime.utcnow()`)
+
+## Versioning
+
+Follow [semantic versioning](https://semver.org/): **MAJOR.MINOR.PATCH**
+
+Version is managed in `pyproject.toml` (line 3). When making changes that warrant a version bump:
+
+1. **Suggest the appropriate version bump** based on the changes made
+2. **Ask for user approval** before updating `pyproject.toml`
+
+### Version Bump Rules
+
+- **MAJOR (x.0.0)**: Breaking changes
+  - Removed or renamed public methods/parameters
+  - Changed method signatures (removed parameters, changed parameter order)
+  - Dropped Python version support
+  - Changed response model fields (removed/renamed)
+
+- **MINOR (0.x.0)**: New features (backward compatible)
+  - New endpoints/methods added
+  - New optional parameters added
+  - New response model types added
+  - New convenience features
+
+- **PATCH (0.0.x)**: Bug fixes and non-breaking changes
+  - Bug fixes
+  - Documentation improvements
+  - Internal refactoring (no public API changes)
+  - Dependency updates (non-breaking)
+
+**Note**: While in `0.x.x`, the API is considered unstable and breaking changes may occur in MINOR versions.

CONTRIBUTING.md

@@ -0,0 +1,140 @@
+# Contributing to Nansen Python SDK
+
+Thank you for considering contributing to the Nansen Python SDK! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/nansen-ai/nansen-python-sdk.git
+   cd nansen-python-sdk
+   ```
+
+2. **Install dependencies**
+   ```bash
+   poetry install
+   ```
+
+3. **Set up pre-commit hooks**
+   ```bash
+   poetry run pre-commit install
+   ```
+
+## Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run with coverage
+poetry run pytest --cov=src/nansen
+
+# Run specific test file
+poetry run pytest tests/test_resources/test_tgm.py
+```
+
+## Code Quality
+
+Before submitting a PR, ensure your code passes all checks:
+
+```bash
+# Lint with Ruff
+poetry run ruff check .
+
+# Format with Ruff
+poetry run ruff format .
+
+# Type check with mypy
+poetry run mypy src/
+```
+
+Pre-commit hooks will automatically run these checks, but you can run them manually as well.
+
+## Code Style
+
+- **Python 3.10+ compatibility**: Use `from __future__ import annotations` instead of `X | Y` unions in runtime code
+- **Line length**: 100 characters (enforced by Ruff)
+- **Type hints**: All public methods must have type hints
+- **Docstrings**: Use Google-style docstrings for public methods
+- **Imports**: Sorted by Ruff (use `ruff check --fix` to auto-sort)
+
+## Project Conventions
+
+- **NOT_GIVEN sentinel**: Optional params default to `NOT_GIVEN` (not `None`)
+- **Sync/async mirroring**: Every resource has both sync and async classes with identical signatures
+- **Response models**: All response models extend `BaseModel` (pydantic v2) with `Optional` fields
+- **Pagination**: Use `SyncPage[T]` / `AsyncPage[T]` for paginated endpoints
+
+## Adding a New Endpoint
+
+1. **Add response model** in `src/nansen/types/<resource>.py`
+2. **Add method** to both sync and async classes in `src/nansen/resources/<resource>.py`
+3. **Export types** from `src/nansen/__init__.py` if public
+4. **Add test** in `tests/test_resources/` using `respx` mocks
+5. **Add example** as `examples/try_*.py` script
+6. **Update CHANGELOG.md** under `[Unreleased]`
+
+## Pull Request Process
+
+1. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the code style guidelines
+
+3. **Add tests** for any new functionality
+
+4. **Update documentation**:
+   - Add docstrings to new methods
+   - Update README.md if adding user-facing features
+   - Add entry to CHANGELOG.md under `[Unreleased]`
+
+5. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "feat: add support for X endpoint"
+   ```
+
+   Use conventional commit prefixes:
+   - `feat:` — new feature
+   - `fix:` — bug fix
+   - `docs:` — documentation changes
+   - `test:` — test additions/changes
+   - `refactor:` — code refactoring
+   - `chore:` — maintenance tasks
+
+6. **Push and create PR**:
+   ```bash
+   git push -u origin feature/your-feature-name
+   ```
+
+   Then open a pull request on GitHub with:
+   - Clear description of changes
+   - Reference any related issues
+   - Screenshots/examples if applicable
+
+7. **Respond to feedback**: Address any review comments
+
+## Testing Your Changes
+
+If you've added a new endpoint, test it manually:
+
+```bash
+export NANSEN_API_KEY="your-key"
+poetry run python examples/try_your_endpoint.py
+```
+
+## Questions?
+
+- Check existing [issues](https://github.com/nansen-ai/nansen-python-sdk/issues)
+- Open a new issue for bugs or feature requests
+- Reach out to maintainers for guidance
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.