Contributing to fsspec-utils

Development Has Moved

fsspec-utils is deprecated. Development has moved to fsspeckit.

• ✅ New features: Contribute to fsspeckit
• ⚠️ Bug fixes: Only critical fixes accepted for fsspec-utils
• 🔄 All new development: Goes to fsspeckit

Contribute to fsspeckit →

---

We welcome limited contributions to fsspec-utils for critical bug fixes only. For new features and enhancements, please contribute to fsspeckit instead.

How to Contribute

Reporting Issues

For fsspeckit: Please open an issue on fsspeckit GitHub Issues

For fsspec-utils (legacy, critical bugs only): Open an issue on fsspec-utils GitHub Issues

When reporting an issue, please include: - A clear and concise description of the problem. - Steps to reproduce the behavior. - Expected behavior. - Screenshots or error messages if applicable. - Your fsspec-utils version and Python environment details.

Submitting Pull Requests

Preferred: Submit pull requests to fsspeckit for all new features and improvements.

For fsspec-utils (critical bug fixes only): To submit a critical bug fix to fsspec-utils:

1. Fork the Repository: Start by forking the fsspec-utils repository on GitHub.
2. Clone Your Fork: Clone your forked repository to your local machine.

   git clone https://github.com/your-username/fsspec-utils.git
   cd fsspec-utils
   

3. Create a New Branch: Create a new branch for your changes.

   git checkout -b feature/your-feature-name
   # or
   git checkout -b bugfix/issue-description
   

4. Make Your Changes: Implement your bug fix or feature.
5. Write Tests: Ensure your changes are covered by appropriate unit tests.
6. Run Tests: Verify all tests pass before submitting.

   uv run pytest
   

7. Format Code: Ensure your code adheres to the project's style guidelines. The project uses ruff for linting and formatting.

   uv run ruff check . --fix
   uv run ruff format .
   

8. Commit Your Changes: Write clear and concise commit messages.

   git commit -m "feat: Add new awesome feature"
   

9. Push to Your Fork: Push your branch to your forked repository.

   git push origin feature/your-feature-name
   

10. Open a Pull Request: Go to the original fsspec-utils repository on GitHub and open a pull request from your new branch. Provide a detailed description of your changes.

Development Setup

To set up your development environment, follow these steps:

1. Clone the repository:

   git clone https://github.com/fsspec/fsspec-utils.git
   cd fsspec-utils
   

2. Install uv: fsspec-utils uses uv for dependency management and running commands. If you don't have uv installed, you can install it via pip:

   pip install uv
   

3. Install Development Dependencies: The project uses uv to manage dependencies. Install the dev dependency group which includes tools for testing, linting, and documentation generation.

   uv pip install -e ".[dev]"
   

   This command installs the project in editable mode (-e) and includes all development-related dependencies specified in pyproject.toml under the [project.optional-dependencies] dev section.

Best Practices for Contributions

• Code Style: Adhere to the existing code style. We use ruff for linting and formatting.
• Testing: All new features and bug fixes should be accompanied by relevant unit tests.
• Documentation: If your changes introduce new features or modify existing behavior, please update the documentation accordingly.
• Commit Messages: Write descriptive commit messages that explain the purpose of your changes.
• Atomic Commits: Try to keep your commits focused on a single logical change.
• Branch Naming: Use clear and concise branch names (e.g., feature/new-feature, bugfix/fix-issue-123).