From 5a3bc791ccd17cf8b902459808668c055680cd74 Mon Sep 17 00:00:00 2001
From: Austin Raney <aaraney@protonmail.com>
Date: Wed, 29 Jun 2022 21:51:22 -0400
Subject: [PATCH] update contribution.md to resolve #143.

---
 CONTRIBUTING.md | 138 +++++++++++++++++++++++++++---------------------
 1 file changed, 79 insertions(+), 59 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 81808ae2..a25f9481 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,9 +1,9 @@
 # Guidance on how to contribute
 
 There are two primary ways to help:
- - Using the issue tracker, and
- - Changing the code-base.
 
+- Using the issue tracker, and
+- Changing the code-base.
 
 ## Using the issue tracker
 
@@ -23,7 +23,6 @@ unit tests that validate implemented features and the presence or lack of defect
 Additionally, the code should follow any stylistic and architectural guidelines
 prescribed by the project.
 
-
 ## Contribution Guidelines
 
 ### Setting Up Development Environment
@@ -104,70 +103,76 @@ This project uses python native `namespace` packaging as outlined introduced in
 
 ```bash
 python
-├── my_subpackage/
-   ├── hydrotools/
-   │   └── my_subpackage/
-   │       ├── __init__.py
-   │       └── foo.py
-   │       └── bar.py
-   ├── setup.py
-   ├── pyproject.toml
-   └── tests/
+└── my_subpackage/
+    ├── src/
+    │   └── hydrotools/
+    │       └── my_subpackage/
+    │           ├── __init__.py
+    │           ├── foo.py
+    │           └── _version.py
+    ├── tests/
+    ├── CONTRIBUTION.md -> ../../CONTRIBUTION.md
+    ├── LICENSE -> ../../LICENSE
+    ├── SECURITY.md -> ../../SECURITY.md
+    ├── TERMS.md -> ../../TERMS.md
+    ├── README.md
+    ├── pyproject.toml
+    ├── pytest.ini -> ../../pytest.ini
+    └── setup.cfg
 ```
 
-3. The package's `setup.py` should use the following template:
+3. The package's `setup.cfg` should use the following template:
+
+```ini
+[metadata]
+name = hydrotools.{{ SUBPACKAGE_NAME }}
+version = attr: hydrotools.{{ SUBPACKAGE_NAME }}._version.__version__
+author = {{ AUTHOR }}
+author_email = {{ AUTHOR_EMAIL }}
+description = {{ SHORT_DESCRIPTION }}
+long_description = file: README.md
+long_description_content_type = text/markdown; charset=UTF-8
+license = USDOC
+license_files =
+    LICENSE
+url = https://github.com/NOAA-OWP/hydrotools
+project_urls =
+    Documentation = https://noaa-owp.github.io/hydrotools/hydrotools.{{ SUBPACKAGE_NAME }}.html
+    Source = https://github.com/NOAA-OWP/hydrotools/tree/main/python/nwm_client
+    Tracker = https://github.com/NOAA-OWP/hydrotools/issues
+classifiers =
+    Development Status :: 3 - Alpha
+    Intended Audience :: Education
+    Intended Audience :: Science/Research
+    License :: Free To Use But Restricted
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Topic :: Scientific/Engineering :: Hydrology
+    Operating System :: OS Independent
+
+[options]
+packages = find_namespace:
+package_dir =
+    =src
+install_requires =
+  {{ PACKAGE_REQUIREMENTS }}
+python_requires = >=3.7
+include_package_data = True
+
+[options.packages.find]
+where = src
+
+[options.extras_require]
+develop =
+    pytest
 
-```python
-#!/usr/bin/env python3
-from setuptools import setup, find_namespace_packages
-
-# python namespace subpackage
-# this namespace package follows PEP420
-# https://packaging.python.org/guides/packaging-namespace-packages/#native-namespace-packages
-
-NAMESPACE_PACKAGE_NAME = "hydrotools"
-SUBPACKAGE_NAME = "{{ SUBPACKAGE_NAME }}"
-
-# Namespace subpackage slug.
-# Ex: mypkg.a # Where the namespace pkg = `mypkg` and the subpackage = `a`
-SUBPACKAGE_SLUG = f"{NAMESPACE_PACKAGE_NAME}.{SUBPACKAGE_NAME}"
-
-# Subpackage version
-VERSION = "0.1.0"
-
-# Package author information
-AUTHOR = "{{ AUTHOR }}"
-AUTHOR_EMAIL = "{{ AUTHOR_EMAIL }}"
-
-# Short sub-package description
-DESCRIPTION = "{{ SHORT_DESCRIPTION }}"
-
-# Package dependency requirements
-REQUIREMENTS = []
-
-# Development requirements
-DEVELOPMENT_REQUIREMENTS = ["pytest"]
-
-setup(
-    name=SUBPACKAGE_SLUG,
-    version=VERSION,
-    author=AUTHOR,
-    author_email=AUTHOR_EMAIL,
-    classifiers=["Private :: Do Not Upload to pypi server",],
-    description=DESCRIPTION,
-    namespace_packages=[NAMESPACE_PACKAGE_NAME],
-    packages=find_namespace_packages(
-        include=[f"{NAMESPACE_PACKAGE_NAME}.*"]
-    ),
-    install_requires=REQUIREMENTS,
-    extras_require={"develop": DEVELOPMENT_REQUIREMENTS},
-)
 ```
 
 4. The package's `pyproject.toml` should use the following template and add any
 build-system requirements:
 
-```
+```toml
 [build-system]
 build-backend = "setuptools.build_meta"
 requires = [
@@ -177,4 +182,19 @@ requires = [
 
 ```
 
+5. `_version.py` should use the following template:
+
+```python
+__version__ = "0.0.1"
+
+```
+
+6. `__init__.py` must start with the following:
+
+```python
+# removing __version__ import will cause build to fail. see: https://github.com/pypa/setuptools/issues/1724#issuecomment-627241822
+from ._version import __version__
+
+```
+
 Further explanation of the rational behind this pattern and more verbose explanation can be found in #12.