From 2ffc919b318d762339543df10f17f83d52cc4ae2 Mon Sep 17 00:00:00 2001
From: Iustin Pop <iustin@k1024.org>
Date: Mon, 17 Apr 2023 23:07:31 +0200
Subject: [PATCH] Add a CONTRIBUTING.md file
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit
I was not sure this is really useful, but after writing it, definitely
so. At least I finally documented the release steps ð
---
CONTRIBUTING.md | 65 +++++++++++++++++++++++++++++++++++++++++++++
README.md | 2 ++
doc/contributing.md | 1 +
doc/index.rst | 1 +
4 files changed, 69 insertions(+)
create mode 100644 CONTRIBUTING.md
create mode 120000 doc/contributing.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a753313
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,65 @@
+# Contributing to pyxattr
+
+Hi, and thanks for any and all contributions!
+
+## Bugs and patches
+
+This is a small project, so let's keep things simple:
+
+- Please file all bug reports on github
+ (<https://github.com/iustin/pyxattr/issues>), as this allows
+ archival and discovery by other people;
+- Send patches as pull requests; for larger changes, would be good to
+ first open a bug to discuss the plans;
+
+Due to simplicity, there are no old branches being kept alive, but if
+it ever happens that a bug is found in older versions and there is
+needed to support older Python versions, it is possible to do so.
+
+## Code standards
+
+There are no formal standards, but:
+
+- Code should be tested - this is why there's a [Codecov
+ integration](https://app.codecov.io/gh/iustin/pyxattr/tree/main).
+- New functions should have good docstrings (in the C code).
+- New functions/constants should be listed in the documentation, see
+ `doc/module.rst` for how to include them.
+- All non-trivial changes should be listed in `NEWS` for further
+ inclusion in new releases documentation. Add an "unreleased" section
+ (if one doesn't exist yet) to list the changes.
+
+## Release process
+
+Right now, due to GPG signing, I'm doing releases and signing them
+manually (offline, I mean). Basically, once GitHub workflows are fine:
+
+- Bump the version in all places - use `git grep -F $OLD_VER` and
+ update as needed.
+- Ensure that `setup.py` has the right Python versions listed (bit me
+ more than once).
+- Update the `NEWS` file is up to date (contents), and use the right
+ date.
+- Check that the generated documentation (`make doc`) looks right.
+
+Then run these steps:
+
+```
+$ make clean
+$ make distcheck # this leaves things in dist/
+$ git tag -m 'Release pyxattr-0.0.1' --sign v0.0.1
+$ gpg --sign -b -a dist/pyxattr-0.0.1.tar.gz
+$ python3 -m twine upload dist/*
+```
+
+Separately:
+
+* Upload the `dist/` contents to GitHub and tag a new release.
+* Upload the `dist/` contents to the old-style download area,
+ <https://pyxattr.k1024.org/downloads/>.
+
+Hopefully one day all this can be more automated.
+
+## Signing key
+
+The releases are currently signed by my key, see <https://k1024.org/contact/>.
diff --git a/README.md b/README.md
index d44ac75..4c9db07 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ Downloads: go to <https://pyxattr.k1024.org/downloads/>. The source
repository is either at <https://git.k1024.org/pyxattr.git> or at
<https://github.com/iustin/pyxattr>.
+See the `CONTRIBUTING.md` file for details on how to contribute.
+
## Requirements
The current supported Python versions are 3.7+ (tested up to 3.10), or
diff --git a/doc/contributing.md b/doc/contributing.md
new file mode 120000
index 0000000..44fcc63
--- /dev/null
+++ b/doc/contributing.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index c877731..5c6a7ca 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -12,6 +12,7 @@ Contents
:maxdepth: 2
readme.md
+ contributing.md
security.md
module.rst
news.rst
--
2.39.5