Metadata-Version: 2.4
Name: asfexample
Version: 0.0.5
Summary: Example package for ASF Tooling
Author: ASF Tooling
Author-email: ASF Tooling <dev@tooling.apache.org>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Dist: pygit2>=1.18.1
Requires-Dist: tomlkit>=0.13.3
Requires-Python: >=3.13
Project-URL: Source, https://github.com/apache/tooling-asf-example
Description-Content-Type: text/markdown

# asfexample

**This package does not have official Apache Software Foundation (ASF) releases.**

This is an example test package issued by Tooling at the ASF. It contains no stable user facing functionality. We do not make guarantees about any of the interfaces contained herein, nor the continued existence of this package.

The purpose of this package is to test:

- Proposed package naming conventions and version schemes within ASF Infra and ASF Tooling
- GHA workflows for trickle down use in other ASF Tooling projects
- Interaction with the ATR platform presently under development by ASF Tooling

## Proposed conventions

The proposed packaging conventions are:

- Use `asf${NAME}` or `${NAME}` for PyPI package names, depending on whether the package is for ASF use only or not
- Ensure that package code is in `${NAME}/` only
- Use `0.0.N` for versions, starting with `0.0.1`
- Increment `N` for each released version
- Use `0.0.(N+1).dev0+dev` for non-release `main` commits, starting with `0.0.1.dev0+dev`

The `+dev` makes it a local version, which PyPI will not accept, so a build from source can never be published as a release. The `.dev0` makes it a pre-release, so installers that can see both choose the release.

A package having three commits on `main`, then a release, then two more commits to `main`, then another release, will for example use the following versions:

```
0.0.1.dev0+dev
0.0.1.dev0+dev
0.0.1.dev0+dev
0.0.1
0.0.2.dev0+dev
0.0.2.dev0+dev
0.0.2
```

These packaging conventions are proposed only for ASF Infra and Tooling packages which will be published to PyPI. Other packages, for internal use, may use any packaging conventions. Aligning with these conventions, if adopted, would, however, make it easier to promote internal packages to PyPI.

## Releasing

To release `0.0.N`, run `uv version 0.0.N`, commit, tag that commit `v0.0.N`, and push both together with `git push --atomic origin main v0.0.N`. A tag pushed on its own after its commit is not checked by the hooks.

The upload waits until two members of ASF Tooling approve it at https://releases.apache.org/gates.

Afterwards, run `uv version 0.0.(N+1).dev0+dev` with the next number filled in, commit, and push. Always set the version explicitly: `uv version --bump stable` keeps the `+dev`.

## Development

Run `uv run prek install` once after cloning. Its hooks run the linters and check the version scheme on every commit, and add the type checks and tests on every push.
