diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..ea5543e1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,89 @@ +# Quickstart + +python-arango is a Python driver for ArangoDB. Run the commands below from the +repository root. + +## Repository layout + +- `arango/`: driver implementation, public APIs, and type annotations. +- `tests/`: pytest tests; `conftest.py` defines database fixtures and CLI options. +- `tests/static/`: server configurations and test data used by `starter.sh`. +- `docs/`: Sphinx documentation in reStructuredText. +- `pyproject.toml`, `setup.cfg`, `.pre-commit-config.yaml`: packaging and tooling. +- `.circleci/`, `.github/workflows/`: CI checks, documentation, and publishing. + +## Development setup + +Use Python 3.10 or newer. Create a virtual environment, or use an existing one: + +```bash +python3 -m venv .venv # Create an isolated Python environment. +source .venv/bin/activate # Use its interpreter and tools. +python -m pip install -e '.[dev]' # Install the editable driver and dev tools. +pre-commit install # Enable checks before each commit. +``` + +Examples use `python` from the activated environment. If it is unavailable on +PATH, invoke your environment's interpreter directly. + +## Local cluster and tests + +The starter requires Docker, Bash, `wget`, and `jq`. To replace an existing test +container, run `docker stop arango` and `docker rm arango` first. + +```bash +version="latest" # Or pin a supported version, such as 3.12.10. +./starter.sh cluster enterprise "$version" # Start a local test cluster. +python -m pytest --cluster # Run the full suite against the cluster. +# Run one test while developing a document change. +python -m pytest --cluster tests/test_document.py::test_document_insert +# Generate an HTML coverage report. +python -m pytest --cluster --cov=arango --cov-report=html +``` + +Defaults are `127.0.0.1:8529`, user `root`, password `passwd`, and JWT secret +`secret`, matching the starter configuration. Override them with `--host`, +`--port`, `--root`, `--password`, and `--secret`. Use a disposable development +database: tests create and delete databases, users, jobs, and backups. If a +sandbox blocks localhost access, rerun with the required sandbox permission. + +For a single server, use `./starter.sh single enterprise "$version"` and omit +`--cluster`. Import tests can run without ArangoDB: + +```bash +python -m pytest tests/test_imports.py --skip-arango-setup # Check imports offline. +``` + +## Style and documentation + +Run the configured hooks for formatting, import ordering, linting, and type +checks. Build and test documentation separately: + +```bash +pre-commit run --all-files # Run hooks; formatters may modify files. +python -m sphinx -b html docs docs/_build # Build the HTML documentation. +python -m sphinx -b doctest docs docs/_build # Test documentation examples. +``` + +The Sphinx doctests require a running ArangoDB server. Open +`docs/_build/index.html` for the HTML documentation or `htmlcov/index.html` for +the coverage report. + +## Changes and pull requests + +- Agents must work on a branch other than `main`; never commit directly to `main`. + Check the current branch before editing or committing. If on `main` or a + detached HEAD, create a branch first: + + ```bash + git branch --show-current # Check the current branch. + git switch -c fix/describe-change # Choose a descriptive branch name. + ``` + +- Preserve public API compatibility unless a breaking change is intentional. +- Follow existing code patterns, type annotations, and Sphinx docstrings. +- Add regression tests for fixes and tests for new behavior; update user documentation. +- Run relevant tests and checks; report anything skipped and why. +- Keep test coverage up and squash changes into one commit for submission. +- Use present-tense commit messages, such as `Fix cursor retry`. +- Explain what changed, why, and any compatibility impact in the pull request. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 375d8b0a..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,28 +0,0 @@ -# Contributing - -Set up dev environment: -```shell -cd ~/your/repository/fork # Activate venv if you have one (recommended) -pip install -e .[dev] # Install dev dependencies (e.g. black, mypy, pre-commit) -pre-commit install # Install git pre-commit hooks -``` - -Run unit tests with coverage: - -```shell -pytest --cov=arango --cov-report=html # Open htmlcov/index.html in your browser -``` - -To start and ArangoDB instance locally, run: - -```shell -./starter.sh # Requires docker -``` - -Build and test documentation: - -```shell -python -m sphinx docs docs/_build # Open docs/_build/index.html in your browser -``` - -Thank you for your contribution! diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 09332329..00000000 --- a/docs/contributing.rst +++ /dev/null @@ -1,99 +0,0 @@ -Contributing ------------- - -Requirements -============ - -Before submitting a pull request on GitHub_, please make sure you meet the -following requirements: - -* The pull request points to main_ branch. -* Changes are squashed into a single commit. I like to use git rebase for this. -* Commit message is in present tense. For example, "Fix bug" is good while - "Fixed bug" is not. -* Sphinx_-compatible docstrings. -* PEP8_ compliance. -* No missing docstrings or commented-out lines. -* Test coverage remains at %100. If a piece of code is trivial and does not - need unit tests, use this_ to exclude it from coverage. -* No build failures. Builds automatically trigger on pull - request submissions. -* Documentation is kept up-to-date with the new changes (see below). - -.. warning:: - The dev branch is occasionally rebased, and its commit history may be - overwritten in the process. Before you begin your feature work, git fetch - or pull to ensure that your local branch has not diverged. If you see git - conflicts and want to start with a clean slate, run the following commands: - - .. code-block:: bash - - ~$ git checkout dev - ~$ git fetch origin - ~$ git reset --hard origin/dev # THIS WILL WIPE ALL LOCAL CHANGES - -Style -===== - -To ensure PEP8_ compliance, run flake8_: - -.. code-block:: bash - - ~$ pip install flake8 - ~$ git clone https://github.com/arangodb/python-arango.git - ~$ cd python-arango - ~$ flake8 - -If there is a good reason to ignore a warning, see here_ on how to exclude it. - -Testing -======= - -To test your changes, you can run the integration test suite that comes with -**python-arango**. It uses pytest_ and requires an actual ArangoDB instance. - -To run the test suite (use your own host, port and root password): - -.. code-block:: bash - - ~$ pip install pytest - ~$ git clone https://github.com/arangodb/python-arango.git - ~$ cd python-arango - ~$ pytest --cluster --host=127.0.0.1 --port=8529 --password=passwd - -To run the test suite with coverage report: - -.. code-block:: bash - - ~$ pip install coverage pytest pytest-cov - ~$ git clone https://github.com/arangodb/python-arango.git - ~$ cd python-arango - ~$ pytest --cluster --host=127.0.0.1 --port=8529 --password=passwd --cov=kq - -As the test suite creates real databases and jobs, it should only be run in -development environments. - -Documentation -============= - -The documentation including the README is written in reStructuredText_ and uses -Sphinx_. To build an HTML version on your local machine: - -.. code-block:: bash - - ~$ pip install sphinx sphinx_rtd_theme - ~$ git clone https://github.com/arangodb/python-arango.git - ~$ cd python-arango - ~$ python -m sphinx -b html -W docs docs/_build/ # Open build/index.html in a browser - -As always, thank you for your contribution! - -.. _main: https://github.com/arangodb/python-arango/tree/main -.. _GitHub: https://github.com/arangodb/python-arango -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ -.. _this: http://coverage.readthedocs.io/en/latest/excluding.html -.. _Sphinx: https://github.com/sphinx-doc/sphinx -.. _flake8: http://flake8.pycqa.org -.. _here: http://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors -.. _pytest: https://github.com/pytest-dev/pytest -.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText diff --git a/docs/index.rst b/docs/index.rst index 4b947c41..b415e772 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -94,7 +94,6 @@ Development .. toctree:: :maxdepth: 1 - contributing specs .. _ArangoDB: https://www.arangodb.com diff --git a/starter.sh b/starter.sh index 612fbee1..fc4606f5 100755 --- a/starter.sh +++ b/starter.sh @@ -10,9 +10,10 @@ # ./starter.sh cluster enterprise 3.12.4 # ./starter.sh single core-preview 4.0-nightly # ./starter.sh single arangodb/enterprise-preview:3.12-nightly +# Defaults: single server, enterprise image, latest version. setup="${1:-single}" -image="${2:-community}" +image="${2:-enterprise}" version="${3:-latest}" extra_ports=""