Add version information and help docs for conda. (#344)

* Add version information and help docs for conda.

* Remove use_gitlfs option.

.github/workflows/ci.yml

@@ -36,7 +36,6 @@ jobs:
               --data mypy_type_checking=basic
               --data create_example_module=no
               --data include_notebooks=no
-              --data use_gitlfs=disabled
             foldername: 'black_w_o_example_module'
           - name: Black w/ example
             package_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
@@ -51,7 +50,6 @@ jobs:
               --data mypy_type_checking=basic
               --data create_example_module=yes
               --data include_notebooks=no
-              --data use_gitlfs=disabled
             foldername: 'black_w_example_module'
           - name: Pylint w/o example
             package_name: 'drewtonian' # Same module name provided in `extra_flags` on the next line.
@@ -66,7 +64,6 @@ jobs:
               --data mypy_type_checking=basic
               --data create_example_module=no
               --data include_notebooks=no
-              --data use_gitlfs=disabled
             foldername: 'pylint_w_o_example_module'
           - name: No sphinx docs
             package_name: 'drewtonian'

copier.yml

@@ -117,16 +117,6 @@ include_benchmarks:
         no: false
     when: "{{ custom_install }}"
 
-use_gitlfs:
-    help: Do you want to add a .gitattributes with entries for git-lfs (see https://lincc-ppt.readthedocs.io/en/latest/practices/git-lfs.html)?
-    type: str
-    default: none
-    choices:
-        maybe later: none
-        yes .gitattributes with example entries disabled: disabled
-        yes .gitattributes with example entries enabled: enabled
-    when: "{{ custom_install }}"
-
 ###
 # Below this line are Copier configuration options.
 ###
@@ -136,7 +126,6 @@ _subdirectory: python-project-template
 
 _skip_if_exists:
     - README.md
-    - .gitattributes
 
 # Require that the user has at least Copier v8.0.0 installed
 _min_copier_version: "8.0.0"

docs/index.rst

@@ -37,6 +37,7 @@ We think it's really neat, and we hope you do to!
    practices/pipx
    practices/precommit
    practices/pypi
+   practices/conda
    practices/unit_testing
    practices/pytest_timeout
    practices/sphinx

docs/practices/conda.rst

@@ -0,0 +1,43 @@
+Conda
+===============================================================================
+
+What is it? Why do it?
+-------------------------------------------------------------------------------
+
+Conda is a package manager.
+
+It's pretty special because it works across whatever language you're using, in
+whatever platform you're using. 
+
+See also packaging with :doc:`pypi`.
+
+How to manage
+-------------------------------------------------------------------------------
+
+Set-up
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Conda requires the version information to be contained in the bundled source tree.
+We include a file in the root-level of the project directory - ``.git_archival.txt`` -
+that ``setuptools_scm`` knows how to hydrate. This is triggered in git via a line
+in the ``.gitattributes`` file. You shouldn't need to change anything in your
+main project repo.
+
+There is some initial set-up that requires human intervention.
+Read `conda's instructions for adding packages <https://conda-forge.org/docs/maintainer/adding_pkgs.html>`_.
+
+You will want to fork `staged-recipes <https://github.com/conda-forge/staged-recipes/>`_
+and add your "recipe" to a subdirectory in ``staged-recipes/recipes``.
+You will send this off as a PR to the conda-forge team and 
+once approved, your recipe will be moved to a "feedstock" repo of its own.
+
+Releasing new versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You will 
+`create a new release <https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release>`_ 
+from your repository as normal.
+
+conda-forge periodically looks at your source repo for any new releases/tags, 
+tries to build a new release, and pre-generates the PR (against your "feedstock"
+repo created above) to publish the new version of the package.

docs/practices/pypi.rst

@@ -9,6 +9,7 @@ published via PyPI, a package can be installed on anyone's development environme
 with ``pip`` or ``conda`` commands. 
 PyPI makes versioning and sharing your software products easy.
 
+See also packaging with :doc:`conda`.
 
 How to manage
 -------------------------------------------------------------------------------

python-project-template/.git_archival.txt

@@ -0,0 +1,4 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$
+ref-names: $Format:%D$

python-project-template/{% if use_gitlfs == 'disabled' %}.gitattributes{% endif %}.jinja → python-project-template/.gitattributes

@@ -1,6 +1,7 @@
 # For explanation of this file and uses see
 # https://git-scm.com/docs/gitattributes
 # https://developer.lsst.io/git/git-lfs.html#using-git-lfs-enabled-repositories
+# https://lincc-ppt.readthedocs.io/en/latest/practices/git-lfs.html
 #
 # Used by https://github.com/lsst/afwdata.git
 # *.boost filter=lfs diff=lfs merge=lfs -text
@@ -19,3 +20,5 @@
 #
 # png image files
 # *.png	filter=lfs diff=lfs merge=lfs -text
+
+.git_archival.txt export-subst