{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Contributing to xsnow\n",
    "\n",
    "Contributions from users, developers, and researchers are welcome---whether you are reporting a bug, suggesting an improvement, or developing new features."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. How to get started\n",
    "\n",
    "You can contribute to `xsnow` in several ways:\n",
    "\n",
    "- **Report bugs** or unexpected behavior\n",
    "- **Suggest improvements** to the API, implementation, or documentation\n",
    "- **Submit merge requests** with code or documentation\n",
    "\n",
    "Development and collaboration is managed through AvaCollabra's Gitlab group. The repository is accessible at [https://gitlab.com/avacollabra/postprocessing/xsnow](https://gitlab.com/avacollabra/postprocessing/xsnow). \n",
    "\n",
    "To contribute, please sign up to GitLab and submit issues or merge requests through the xsnow repository.\n",
    "You can find the relevant links in the repository itself, or by hovering over the GitLab fox icon at the top of this page."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Reporting bugs and suggesting improvements\n",
    "\n",
    "You can report bugs or suggest improvements directly through the **GitLab issue tracker**.\n",
    "\n",
    "Use the **“Open issue”** link by hovering over the Gitlab fox icon at the top of this page.\n",
    "\n",
    "When reporting a bug, please include:\n",
    "\n",
    "- A **clear description** of the problem\n",
    "- Steps to reproduce (ideally with a small code example)\n",
    "- Your system and environment (OS, xsnow version)\n",
    "- Expected vs. actual behavior\n",
    "\n",
    "If you are suggesting improvements:\n",
    "- Briefly sketch the status quo\n",
    "- Explain the use case of the modification or new feature and why it adds value\n",
    "- Include a minimal sketch or example if possible"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```{tip}\n",
    "You can also suggest improvements to documentation or tutorials directly via the **“Suggest edit”** link. This opens a pre-filled merge request with your changes.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Submitting changes via merge requests\n",
    "\n",
    "To propose changes to the code or documentation:\n",
    "\n",
    "1. Create a new branch from `dev` (see the next section on *Branch strategy*).\n",
    "2. Implement your changes and commit them with clear, descriptive messages.  \n",
    "   *Tip:* Follow this excellent short guide on [how to write a good commit message](https://cbea.ms/git-commit/).\n",
    "3. Open a merge request in GitLab targeting the `dev` branch.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Merge request checklist\n",
    " - New features come with tests\n",
    " - Code runs without errors and passes local tests.\n",
    " - Documentation strings (`docstrings`) are complete.\n",
    " - Tutorials and docstring examples are updated if the interface changed.\n",
    " - No temporary debug prints or unused imports remain.\n",
    " - The feature branch merges cleanly into `dev` (no pending merge conflicts)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f441cd2",
   "metadata": {},
   "source": [
    "## 4. Branch strategy\n",
    "\n",
    "`xsnow` uses a simple and transparent **branching model** that keeps development organized.\n",
    "\n",
    "| Branch | Purpose | Description |\n",
    "|:--|:--|:--|\n",
    "| `main` | Stable branch | Contains the latest **stable** version of `xsnow`. Every commit here is deployable and well tested. |\n",
    "| `dev` | Development branch | Used for **active integration** of new features and fixes before merging to `main`. |\n",
    "| `feature/*` | New features | For developing new functionality or modules. Example: `feature/dask`. |\n",
    "| `fix/*` | Bug fixes | For resolving issues found during testing or usage. Example: `fix/parser`. |\n",
    "| `chore/*` | Chores | For refactoring, maintenance, etc. |\n",
    "| `docs/*` | Documentation | For improving or extending documentation/tutorials. |\n",
    "\n",
    "### Key guidelines\n",
    "- Always branch off from **`dev`**\n",
    "- Keep your branch focused---one topic, one branch.\n",
    "- Maintainers will handle reviews, approvals, and merges into `main` for release.\n",
    "\n",
    "\n",
    "```{note}\n",
    "Think of `main` as the **stable** (released) branch and `dev` as the **active integration** branch.  \n",
    "Feature branches are short-lived and should be merged or deleted once completed.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Testing strategy\n",
    "\n",
    "`xsnow` uses **pytest** for automated testing.\n",
    "\n",
    "To run the test suite locally:\n",
    "```bash\n",
    "cd xsnow\n",
    "pytest\n",
    "```\n",
    "\n",
    "All tests are located in the `tests/` directory and include unit, integration, and performance tests.\n",
    "All new functionality should include appropriate test cases, and any existing tests broken by your changes should ideally be fixed before merging.\n",
    "\n",
    "Further details on the testing structure and conventions are available in `tests/README.md`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Code style \n",
    "\n",
    "We try to follow a clean, modern Python style:\n",
    "\n",
    "- Follow **PEP8**.\n",
    "- Use **type hints** for public interfaces.\n",
    "- Write **docstrings** following the [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).\n",
    "- Each module and function should have a clear description of purpose, parameters, and returns."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Documentation and tutorials\n",
    "\n",
    "Tutorials and API documentation (auto-generated from the source code) live under `docs/`.  \n",
    "To preview locally:\n",
    "\n",
    "```bash\n",
    "cd xsnow/docs/\n",
    "make html\n",
    "```\n",
    "The output appears under `_build/html`. You can view it in your browser.\n",
    "\n",
    "All contributions that add or change functionality should include updates to relevant tutorials or docstrings.\n",
    "\n",
    "```{tip}\n",
    "If you just want to fix a typo or clarify a sentence, use the **“Suggest edit”** link directly from the docs---this will open a merge request automatically.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31a7594d",
   "metadata": {},
   "source": [
    "## 8. CPU versus GPU\n",
    "\n",
    "Developers should make sure that large computations can be carried out on CPU (default) as well as GPU soon as the user environment and installation supports that. Currently, [xsnow.extensions.critical_crack_length](../api/_generated/xsnow.extensions.critical_crack_length) is the only module that implements this capability and can be used as template."
   ]
  }
 ],
 "metadata": {
  "authors": [
   {
    "name": "xsnow Development Team"
   }
  ],
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}