Adding documentation for pulling the template into existing projects.

docs/index.rst

@@ -15,6 +15,7 @@ It's really neat!
 
    source/overview
    source/new_project
+   source/update_project
    source/existing_project
    source/contributing
 

docs/source/existing_project.rst

@@ -1,4 +1,212 @@
-Adding to an existing project
+Incorporating the template into a prior project
 ===============================================================================
 
-TODO - Coming soon!
+These instructions are for those who want to incorporate the latest version of the 
+LINCC Frameworks Python Project Template into an existing project that has not 
+previously used our template. 
+
+If you want to update a project that already uses the template, please see 
+:doc:`Keeping your project up to date <update_project>`.
+
+.. attention ::
+
+    Every pre-existing project is unique - it's a snowflake - even if the developers followed 
+    accepted guidelines and best practices. 
+
+    Because of that, we can't we enumerate all the possible sticking points that you may
+    encounter when attempting to incorporate the LINCC Frameworks Python Project Template 
+    into a pre-existing project.
+
+.. tip ::
+
+    The newer a pre-existing project is, the easier it will be to incorporate the 
+    LINCC Frameworks Python Project Template.
+
+    That being said, we have used this template to bring dormant projects up to date with 
+    modern development standards.
+
+Before you begin
+----------------
+
+Start clean
+...........
+
+It's best to start with a clean local repository and a new git branch just for this task. 
+Copier will not allow the user to merge a template with a git tracked local repository 
+if there are uncommitted changes. 
+
+It's not explicitly necessary, but removing ``cache`` and ``build`` directories will 
+make it easier to see what changes are being made.
+
+Check your environment
+......................
+
+Make sure your system satisfies the :doc:`prerequisites <overview>`.
+
+Hydrate a copy of the template into your project
+................................................
+
+.. code:: bash
+
+    >> cd <existing_project_directory>
+    >> copier gh:lincc-frameworks/python-project-template .
+
+
+A note on directory structure
+.............................
+
+The LINCC Frameworks template does not impose a rigid directory structure. 
+However, some of the tools that the template includes expect that 
+the package source code will be in a first level directory named ``src``, and 
+that tests will be contained in a first level directory named ``tests``.
+
+For example, if your project is in a directory named ``/science``, your source 
+code and tests might look like this:
+
+.. code:: bash
+
+    /science/src/module.py
+    /science/tests/test_module.py
+
+If your directory structure for source code and tests is significantly 
+different than this, it might be worth reorganizing the files in order to make use 
+of the tools (CI, linting, auto documentation) that the template provides.
+
+While running Copier
+--------------------
+
+Reasonable responses to questions
+.................................
+If your project already has a name, especially if it's published on PyPI, it's 
+advised that you use the same name when asked "What is the name of your project?".
+
+If your project has a license already, and it is not one of the licenses listed 
+in the "What license would you like to use?", select "None".
+
+Respond **no** when asked "Do you want to create some example module code?". 
+It's fine to respond "yes", however, given that your project already has an established 
+source code and test directory structure, there's no benefit to including an example 
+module.
+
+Copier work summary
+...................
+
+After Copier has received all your answers, it will begin to hydrate the template 
+with your responses and inject them into your project. 
+As it does so, don't be scared of ``conflict`` markers - remember that everything is git tracked, 
+and Copier does not have the ability permanently overwrite your files.
+
+The following example is output from a Copier update. Note again that ``conflict`` is 
+simply an indicator that you should review that file before committing.
+
+.. code :: bash
+
+    Copying from template version 1.2.1
+    identical  .
+    identical  README.md
+    conflict  .copier-answers.yml
+    overwrite  .copier-answers.yml
+    identical  .gitignore
+    identical  .github/workflows
+    conflict  .github/workflows/linting.yml
+    overwrite  .github/workflows/linting.yml
+    identical  nb/README.md
+    conflict  .pre-commit-config.yaml
+    overwrite  .pre-commit-config.yaml
+    conflict  pyproject.toml
+    overwrite  pyproject.toml
+
+
+After running Copier
+--------------------
+
+Look at what changed
+....................
+
+You should run ``git diff`` to see what code has changed.
+If you don't like the new changes, you can always revert back to the previous state.
+
+Additionally, if Copier encounters a merge conflict between your existing code and 
+the updated template, it will produce ``.rej`` files that contain the unresolved diffs. 
+If you see a ``.rej`` file, resolve the merge conflict and check that your code 
+was updated correctly. 
+There is no need to commit ``.rej`` files, you should remove them as 
+the merge conflicts are resolved.
+
+Confirm that your package builds
+................................
+You should attempt to use ``pip`` to build your package and install dependencies. 
+Failure to build successfully may be an indicator of a corrupted pyproject.toml file
+or missing dependencies.
+
+.. code:: bash
+
+    >> pip install -e .
+    >> pip install .'[dev]'
+
+.. note:: 
+
+    If your existing package uses a setup.py file to build, you will need to move the 
+    important definitions over to pyproject.toml.
+
+    It's likely that you'll only need to move the list of dependencies. But if 
+    there is a significant amount of embedded logic, then this task will become
+    more involved.
+
+    After porting the definitions, remove setup.py and build with ``pip install``. 
+    This will ensure that pyproject.toml is being used for build configuration.
+
+.. warning::
+
+    If your existing package uses a pyproject.toml file and has a hardcoded "version"
+    line similar to ``version: "1.2.0"`` in the ``[project]`` section, please 
+    remove that line.
+
+    The LINCC Frameworks template makes use of dynamic versioning with 
+    ``dynamic = ["version"]``. 
+    A build error will occur if both a hardcoded and dynamic version definition 
+    are present in the same pyproject.toml file.
+
+
+Run all unit tests
+..................
+
+Once you are sure the package still builds, run all the unit tests to ensure that 
+the built package can be imported. The Copier template should not cause any tests 
+to fail.
+
+
+Use pre-commit
+..............
+
+Install and use ``pre-commit``. It may seem annoying at first, but it will save 
+you many cycles of "see a test fail on GitHub, make and push a change, hope the test passes".
+
+
+Import sorting
+..............
+
+If your project wasn't using ``isort`` or something similar before, there's a good 
+chance that pre-commit hook will fail. It will automatically reorder the offending 
+imports. You'll just need to ``git add`` the modified files again.
+
+
+Linters
+.......
+
+If your project wasn't using a linter before, and you chose to include pylint, black, 
+or another linting tool, it's reasonable to skip the linting check on the first commit. 
+
+For instance if you selected ``black`` as your new linter, use the following to 
+bypass the pre-commit linting check on the first commit.
+
+.. code :: bash
+
+    >> SKIP=black git commit -m 'Incorporating LINCC Frameworks PPT'
+
+Linters are opinionated and if your project wasn't using one before there will 
+be a lot of linting errors that will block committing your code.
+
+It's highly recommended that in the next commit after incorporating the template 
+that you address the linting errors so that you don't have to continue to use the 
+``SKIP=...`` command for the rest of your days.

docs/source/new_project.rst

@@ -75,7 +75,7 @@ Use ``pip`` to install both the standard set of dependencies as well as the ``[d
     Lots more output
     ...
 
-You could stop here
+Great, but don't stop here
 -------------------------------------------------------------------------------
 
 At this point, your new project is hydrated and ready for you to start coding. But there's a lot more that this template has to offer. Keep reading to find out more about built in pre-commit hooks, GitHub CI, automatic documentation, and more.
@@ -107,18 +107,3 @@ Create a new repository in GitHub: (`GitHub How-to <https://docs.github.com/en/g
     >> git push origin <local_branch_name>
 
 Notice that when you create a PR in GitHub, a set of tests for Continuous Integration starts up to verify that the project can build successfully and that all the unit tests pass. Neato!
-
-Keep your project up to date
--------------------------------------------------------------------------------
-
-Once your project is under version control you'll be able to keep your project up to date by running the following:
-
-.. code-block:: bash
-
-    >> copier
-
-Yep. That's it.
-
-Copier will automatically check to see if a newer version of the original template is available and if so the changes will be automatically applied. Neato!
-
-And of course, because your project is under version control, if you don't like the new changes, you can always revert back to the previous state.

docs/source/update_project.rst

@@ -0,0 +1,84 @@
+Keeping your project up to date
+===============================
+
+As we release new template features, you can keep your project up to date with 
+a single-word command:
+
+.. code-block:: bash
+
+    >> copier
+
+Copier will automatically check to see if a newer version of the original template 
+is available and if so the changes will be automatically applied. Neato!
+
+You should run ``git diff`` to see what code has changed.
+If you don't like the new changes, you can always revert back to the previous state.
+
+Additionally, if Copier encounters a merge conflict between your existing code and 
+the updated template, it will produce ``.rej`` files that contain the unresolved diffs. 
+If you see a ``.rej`` file, resolve the merge conflict and check that your code 
+was updated correctly. 
+There is no need to commit ``.rej`` files, you should remove them as 
+the merge conflicts are resolved.
+
+There are a few additional flags that you can use to be more explicit about how 
+and what you want to update. We've found the following to be the most useful.
+
+Get the absolute latest version of the template
+-----------------------------------------------
+
+By default, Copier will find and apply the latest tagged release of a template when creating 
+or updating a project. 
+However, there may be new template features that you want to incorporate into your project 
+before they are tagged for release.
+Copier provides the ``--vcs-ref`` flag for this purpose. 
+
+.. code-block:: bash
+
+    >> copier --vcs-ref=HEAD update
+
+Copier will use the latest template from the ``main`` branch and apply it to your project.
+Note that ``HEAD`` can be replaced with any reasonable git tag such as a branch name or 
+commit hash.
+
+Change your response to a single question
+-----------------------------------------
+
+The documentation for Copier indicates that it is a bad idea to manually edit the 
+file that records your responses to the template questions. If you decide that you 
+answered one of the questions incorrectly, you can update it without having to edit 
+the rest.
+
+.. code-block:: bash
+
+    >> copier --force --data <question_name>="new answer" update
+
+This tells copier to use the previous answers for all questions except the one you want to
+update. For instance, if you initialized your project by selected ``pylint`` as your 
+preferred linter, but now would like to change to ``black``, you could use the following:
+
+.. code-block:: bash
+
+    >> copier --force --data preferred_linter="black" update
+
+The full list of questions can be found 
+`here <https://github.com/lincc-frameworks/python-project-template/blob/main/copier.yml>`_.
+
+More information about Copier
+-----------------------------
+
+The maintainers of Copier have written good instructions and there's no point 
+in reproducing it all here. 
+For all the details about updating with Copier checkout the 
+`original documentation <https://copier.readthedocs.io/en/latest/updating/>`_.
+
+Updates to pyproject.toml
+-------------------------
+
+The pyproject.toml file is the primary configuration file for your project. 
+When a project is initially hydrated from the template, a custom pyproject.toml file 
+will be created. Generally Copier updates shouldn't drastically affect this file, 
+but if you are modifying prior answers, take a close look at any changes made to this file.
+
+If something looks incorrect, remember that any changes made by Copier are only *staged for 
+commit*, they are't permanent and can easily be unstaged.