update contril guide and readme (#7)

Author: mdtanker

CONTRIBUTING.md

@@ -363,6 +363,19 @@ Try to get them all passing (green).
 If you have any trouble, leave a comment in the PR or
 [post on the GH discussions page](https://github.com/organizationname/samplepackagename/discussions).
 
+### Sync your fork and local
+
+Once the PR is merged, you will need to sync both your forked repository (origin) and your local clones repository with the following git commands:
+
+```bash
+git fetch upstream
+git checkout main
+git branch -d your-branch-name (OPTIONAL)
+git merge upstream/main
+git push origin main
+```
+Now both your forked (upstream) and local repositories are sync with the upstream repository where the PR was merged.
+
 ## Publish a new release
 
 This will almost always be done by the developers, but as a guide for them, here are instructions on how to release a new version of the package.

README.md

@@ -2,6 +2,8 @@
 
 This template is based on the [Scientific Python Development Guide](https://learn.scientific-python.org/development/). The main differences with the [template they provide](https://github.com/scientific-python/cookie) is that this is an _opinionated_ template, where I made certain decision I feel are optimal. Additional, this is setup for packages which have complex non-Python dependencies which can be installed with `pip`, but require `conda`. This is useful if your package will depends on packages such as `GeoPandas`, `PyGMT`, or `Cartopy`, as these all depend on code written in C or C+ which is easiest to install with conda.
 
+If you just want to host some code but not publish it as a Python package, I have a [simpler template for that](https://github.com/mdtanker/research_repo_template).
+
 The below steps will create a complete Python package with testing, a documentation website, and builds uploaded to both PyPI (pip) and Conda-Forge (conda) for each new version release in GitHub. While it is quite tedious to initially setup, once you finished the below steps, almost everything is automated. The documentation website is automatically generated for each new PR, and new package versions are automatically released to PyPI and Conda-Forge each time you manually create a GitHub release.
 
 ## Packages which have used this template
@@ -44,9 +46,21 @@ Steps:
         git push -u origin new-branch
         ```
     - in the GitHub repository, go to the `Pull request` tab and open a PR for your changes. Merge this into main.
-3) Add your code
-    - pull in your above changes with `git checkout main` and `git merge upstream/main`
-    - if your working off a fork: push the above commit to sync your fork with upstream with `git push origin main`.
+3) Pull in your merged changes
+    - how you do this depends if you pushed your changed directly to the repository, or through a fork of the repository:
+        1) PR submitted directly to repository:
+            - fetch your recent changes: `git fetch`
+            - checkout your main branch: `git checkout main`
+            - OPTIONAL: delete your feature branch: `git branch -d new-branch`
+            - pull in your changes: `git pull`
+        2) PR submitted through a fork:
+            - fetch your recent changes: `git fetch upstream`
+            - checkout your main branch: `git checkout main`
+            - OPTIONAL: delete your feature branch: `git branch -d new-branch`
+            - merge changes from upstream: `git merge upstream/main`
+                - this syncs your local repository to the upstream one
+            - push your changes to your upstream (forked) repository: `git push origin main`
+4) Add your code
     - decide on a module name(s)
         - these need to be lowercase, should be short and while possible, shouldn't include underscores.
         - if your package is going to be small, a single module with the same name as the package is fine. If it's going to be more than a few hundred lines of code, it's best to separate your code into distinct modules which perform similar tasks. - for each module you want do the following:
@@ -69,21 +83,21 @@ Steps:
             ```
             - to allow `function1` to be imported as above, you need to manually add it to the list in `src/samplepackagename/_init_.py`. If you only have 1 module, this may be a better technique.
     - add tests for your modules' test file in `tests/`.
-4) Specify your dependencies
+5) Specify your dependencies
     - dependencies for your package should typically only be those that are directly used (imported) in your source code (or are explicitly needed but not import), but not the dependencies of your dependencies. If you use a package in your documentation, but not in the source code, include this as an _optional_ dependency. If you have a portion of your code that some users may not utilize, such as visualization functions, the dependencies you require for that, such as matplotlib, can also be include as _optional_ dependencies to reduces the constraints for users who don't require it.
     - core dependencies are specified in `pyproject.toml` under the `[project]` section with the format `dependencies = ["pandas", "scipy>=1.0"]`.
     - optional dependencies are specified in `pyproject.toml` under the `[dependency-groups]` section with the following format, for example for optional documentation dependencies: `docs = ["sphinx>=7.0",]`.
     - Dependency version's should only be constrained to specific versions if you know there is an issue, and they should almost never be pinned to specific versions, as this will cause many issues for anyone who wants to use your package in their own environments.
     - this template also includes files and commands to create `conda` environments. These are used both in developing, and in GitHub automations. You need to manually ensure the dependencies listed in `environmental.yml` match those in `pyproject.toml`. Include all optional dependencies in the `environmental.yml`. If a dependency is only available via pip, and not conda, add it at the bottom to be installed via pip.
-5) Create environment, style check, test, and commit your changes.
+6) Create environment, style check, test, and commit your changes.
     - follow the instructions in `CONTRIBUTING.md` starting at section `Setting up nox` and stopping before `Publish a new release`.
     - these steps should result in a merged PR with your code.
-6) Set up automated Zenodo releases (only for Public repositories)
+7) Set up automated Zenodo releases (only for Public repositories)
     - if you haven't already, link your organization (or personal) GitHub account to [Zenodo](https://zenodo.org/) using `Linked accounts` under your Zenodo profile.
     - do to the `GitHub` menu on your Zenodo profile.
     - click the Sync button and then turn on the switch for your repository.
     - any future GitHub releases should now result in a new Zenodo release automatically.
-7) Set up publishing on TestPyPI
+8) Set up publishing on TestPyPI
     - before publishing to the real PyPI, we will publish to Test-PyPI to ensure everything works .
     - make an account on [TestPyPI](https://test.pypi.org/).
     - under 'Your Projects', and 'Publishing', 'Add a new pending publisher', fill out your info.
@@ -92,7 +106,7 @@ Steps:
         - Workflow name should be `cd.yml`
         - Environment name should be `pypi`
     - note that this doesn't reserve your package name until you make your first actual release!
-8) Make a GitHub release
+9) Make a GitHub release
     - On the main GitHub page, on the right side click `Create a new release`.
     - click `Select tag` and type `v0.0.1`.
     - set a Release title: "Initial release"
@@ -107,13 +121,13 @@ Steps:
             pip install -i https://test.pypi.org/simple/ samplepackagename
             nox -s test
             ```
-9) Make a PyPI (pip) release
+10) Make a PyPI (pip) release
     - If the install and test above worked then we can change from TestPyPI to normal PyPI.
     - in `.github/workflows/cd.yml` comment out or delete the last line: `repository-url: https://test.pypi.org/legacy/`. Now any future reruns of this action will release to PyPI.
     - In this case, since the GitHub release has already been made, we need to manually trigger the `CD` workflow in GitHub.
         - At [this link](https://github.com/organizationname/samplepackagename/actions/workflows/cd.yml), click the `Run workflow` button.
         - This should build the package and release it to PyPI.
-10) Set up publishing on Conda-Forge
+11) Set up publishing on Conda-Forge
     - create a [conda-forge recipe and feedstock](https://conda-forge.org/docs/maintainer/adding_pkgs/#creating-recipes) with the below instructions:
         - Create a new environment using : `mamba create --name grayskull grayskull`
         - Activate this new environment : `conda activate MY_ENV`
@@ -124,14 +138,14 @@ Steps:
     - create a new folder : `staged-recipes/recipes/samplepackagename`
     - copy your `meta.yaml` file into this folder, remove the `meta.yaml` from wherever it was generated.
     - commit and push your changes to your fork, and in the main [repository](https://github.com/conda-forge/staged-recipes) open a PR.
-11) Set up ReadTheDocs for the documentation website
+13) Set up ReadTheDocs for the documentation website
     - log into ReadTheDocs using your GitHub account.
     - click `Add project` and ssearch for your repository.
     - Chose your project name, ideally its the same as your package name, but it doesn't have to be. If it's different, update the badge below: `[rtd-link]: https://samplepackagename.readthedocs.io/en/latest/?badge=latest`
     - Go to `settings` to update anything you'd like
         - check `Build pull requests for this project`.
     - for each commit to main, ReadTheDocs should automatically update the documentation website. Also, in PR's there should be a link to view the new docs to check them before merging the PR.
-12) Finalize
+14) Finalize
     - remove all the above instructions and raise any issues in this template's repository if you have any suggestion or found any errors in this template!
     - if you want, please submit a PR to this repository to add your package to this list at the top of this README to showcase it!