Fix: more lesson edits

documentation/repository-files/code-of-conduct-file.md

@@ -1,13 +1,13 @@
-# The CODE_OF_CONDUCT.md file In Your Python Open Source Package
+# The CODE_OF_CONDUCT file - Python Packaging
 
-```{admonition} Example Code of Conduct files
+```{admonition} Example CODE_OF_CONDUCT files
 :class: tip
 
 * [SciPy Code of Conduct file - notice they included theirs in their documentation](https://docs.scipy.org/doc/scipy/dev/conduct/code_of_conduct.html)
-* [fatiando code of conduct file](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)
+* [fatiando CODE_OF_CONDUCT.md file](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)
 ```
 
-Your package should have a **CODE_OF_CONDUCT.md** file located
+Your package should have a `CODE_OF_CONDUCT.md` file located
 the root of the repository. Once you have people using your
 package, you can consider the package itself as having a community
 around it. Some of this community uses your tool. These users
@@ -17,20 +17,20 @@ Others in the community might want to contribute to your tool.
 They might fix bugs, update documentation and engage with the
 maintainer team.
 
-## Why you need a code of conduct
+## Why you need a CODE_OF_CONDUCT
 
 In order to keep this community healthy and to protect yourself,
-your mainatianer team and your users from unhealthy behavior,
-it is important to have a [code of conduct](https://opensource.guide/code-of-conduct/).
+your maintainer team and your users from unhealthy behavior,
+it is important to have a [`CODE_OF_CONDUCT`](https://opensource.guide/code-of-conduct/).
 
-The code of conduct is important
+The `CODE_OF_CONDUCT` is important
 as it establishes what you expect in terms of how users and
 contributors interact with maintainers and each other. It also
 establishes rules and expectations which can then be enforced
-if need be to protect others from harmful and/or negative  behaviors.
+if need be to protect others from harmful and/or negative behaviors.
 
 If you are not comfortable
-with creating your own code of conduct text, we encourage you to adopt the
-code of conduct language used in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
-[Many other communities](https://www.contributor-covenant.org/adopters/) have adopted this code of conduct as
+with creating your own `CODE_OF_CONDUCT` text, we encourage you to adopt the
+`CODE_OF_CONDUCT` language used in the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+[Many other communities](https://www.contributor-covenant.org/adopters/) have adopted this `CODE_OF_CONDUCT` as
 their own. See the [Fatiando a Terra Geoscience Python community's example here.](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md)

documentation/repository-files/license-files.md

@@ -7,27 +7,41 @@
 Want to learn how to add a license file to your GitHub repository? Check out this lesson.
 :::
 
-A license file is important for any open source project to have. The license file helps your users and the community understand:
+## What is a Open Source License file?
 
-1. how they can use your software
-2. whether the software can be reused or adapted for other purposes
-3. how people can (or can't) contribute to your project
+When we talk about LICENSE files, we are referring to a file in your
+GitHub or GitLab repository that contains legally binding language
+that describes to your users how they can legally use  (and not use) your package.
+
+## Why licenses are important
+
+A license file is important for all open source projects because it protects both you as a maintainer and your users. The license file helps your users and the community understand:
+
+1. How they can use your software
+2. Whether the software can be reused or adapted for other purposes
+3. How people can contribute to your project
 
 and more.
 
-## Where to store your license.
+[Read more about why license files are critical in protecting both you as a maintainer and your users of your scientific Python open source package.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)
+
 
-The root of your GitHub / GitLab repository should have a `LICENSE` file that
-contains descriptive text that identifies the type of license that you have
-selected for your software.
+## Where to store your license
+
+Your `LICENSE` file should be stored at root of your GitHub / GitLab repository.
+
+Some maintainers customize the language in their license files for specific reasons. However, if you are just getting started, we suggest that you select a
+permissive license and then use the legal language templates provided both by GitHub and/or the [choosealicense.com](https://choosealicense.com/) website.
+
+Licenses are legally binding, as such you should avoid trying to create your own license unless you have the guidance of legal council.
 
 ### Use open permissive licenses when possible
 
 We generally suggest that you use a permissive, license that is [Open Software Initiative (OSI) approved](https://opensource.org/licenses). If you are
 [submitting your package to pyOpenSci for peer review](https://www.pyopensci.org/about-peer-review/index.html), then we require an OSI approved
 license.
 
-### How to chose a license
+### How to choose a license
 
 To select your license, we suggest that you use GitHub's
 [Choose a License tool ](https://choosealicense.com/).
@@ -46,7 +60,7 @@ with the modified BSD license that SciPy uses.
 
 > Other licenses that are compatible with the modified BSD license that SciPy uses are 2-clause BSD, MIT and PSF. Incompatible licenses are GPL, Apache and custom licenses that require attribution/citation or prohibit use for commercial purposes.
 
-Too coordinate with other packages in our scientific ecosystem, we also recommend
+To coordinate with other packages in our scientific ecosystem, we also recommend
 that you consider using either BSD or MIT as your
 license. If you are unsure, the MIT license tends to be a simpler easier-to-understand option.
 :::
@@ -74,11 +88,13 @@ This means that technically, if you copy code from the Stack Overflow website, a
 :::
 
 
+##  What about software citation?
 
-<!-- TODO: Add discussion of GitHub citation.cff files ??
-i think we need to better understand how this works before adding it...
+While many permissive licenses do not require citation we STRONG encourage that you cite all software that you use in papers, blogs and other publications. You tell your users how to cite your package by using a [citation.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files). We will cover this topic when we talk about creating DOI's for your package using zenodo.
 
+<!-- TODO: add link when lesson is created - but also we don't yet know how citation.cff files work with zenodo (do they work??) will the citation info update with a new zenodo link
 
 These files - we need to understand if that date releases auto populates or forces zenodo to modify it's citation. if it's not dynamic it could be problematic
 
+
 -->

package-structure-code/pyproject-toml-python-package-metadata.md

@@ -65,7 +65,7 @@ Prior to August 2017, Python package metadata was stored either in the `setup.py
 - allows you to use a suite of different [build backends](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html#build-back-ends) such as (flit-core, hatchling, pdm-build), and
 - aligns with modern best practices.
 
-If you are migrating from a **setup.py** or **setup.cfg** file, and want help, [check out this tutorial.](6-setup-py-to-pyproject-toml)
+If you are migrating from a **setup.py** or **setup.cfg** file, and want help, [check out this tutorial.](../tutorials/extras/6-setuppy-to-pyproject-toml.md)
 :::
 
 The standard file that Python packages use to [specify build requirements and

package-structure-code/python-package-distribution-files-sdist-wheel.md

@@ -145,7 +145,7 @@ or is more complex in its build, the two distributions will be very different.
 Also note that we are not discussing conda build workflows in this section.
 [You can learn more about conda builds here.](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html)
 ```
-
+(python-source-distribution)=
 ## Source Distribution (sdist)
 
 **Source files** are the unbuilt files needed to build your
@@ -219,6 +219,7 @@ items including a metadata directory and if you use `setuptools_scm` or `hatch_v
 the sdist may also contain a file that stores the version.
 ```
 
+(python-wheel)=
 ## Wheel (.whl files):
 
 A wheel file is a ZIP-format archive whose filename follows a specific format

tutorials/1-installable-code.md

@@ -1,12 +1,18 @@
 # Make your Python code pip installable
 
+The first step in creating a Python package based on code that you
+have is to make that code pip installable. You will learn how to make
+your code pip installable in this lesson.
+<!-- TODO: make sure it's clear where they add commands!! bash vs python
 
+Bash vs zsh it's different
+-->
 
 :::{figure-md} code-to-script
 
 <img src="../images/tutorials/code-to-script-diagram.png" alt="Diagram showing .. more here if this stays." width="700px">
 
-This is just a concept - if we use change the icons to match the steps
+It might be cool to make another version of this with add license and readme file. and end with build and publish to PyPI. then after that pip install from PyPI This is just a concept - if we use change the icons to match the steps
 :::
 
 :::{admonition} Learning Objectives
@@ -32,44 +38,45 @@ you are a scientist, we suggest that you use `conda`.
 
 :::{figure-md} packages-environment
 
-<img src="../images/environment-package-install.png" alt="Diagram showing .. more here if this stays." width="500px">
+<img src="../images/tutorials/environment-package-install.png" alt="Diagram showing .. more here if this stays." width="700px">
 
-This is an ugly a concept. The graphic should show that you can turn your script into something that can be installed into a contained Python environment. Or you can turn your code into a full package installable from PyPI (or github but we can leave that out to reduce complexity).
+Making your code pip installable is the first step towards creating a Python package. Once it is pip installable, you can add it to any Python environment on your computer and import that package in the same way that you might import a package such as Pandas or Geopandas.
 :::
 
+## Make a basic Python package
+
 It’s time to create the most basic version of a Python package.
 While this code can't be yet published to PyPI or conda and
 is not documented, it will be installable on your computer or
 anyone elses.
 
+### What does a basic package directory structure look like?
 To make your code installable you need:
 
 - A `pyproject.toml` file
 - An (optional but recommended) `__init__.py` file in your code directory
 - A specific directory structure
 - Some code.
 
-### What does a basic package directory structure look like?
-
 The directory structure you’ll create in this first section looks like this:
 
 ```bash
 pyospackage/
      └─ pyproject.toml
-     └─ src/  # the src directory ensures your tests always run on the installed
-             └── pyospackage/ # package directory where code lives, use the package name
+     └─ src/  # The src directory ensures your tests always run on the installed
+             └── pyospackage/ # Package directory where code lives, use the package name
               	      ├── __init__.py
                       ├── add_numbers.py
-                      └──# Add any other .py modules that you want here
+                      └── # Add any other .py modules that you want here
 ```
 
-If you already know what all of the elements of this package structure are, you can skip to the next lesson. Otherwise keep reading to learn about each element of the above structure.
+Below, you will learn about each element of the above package structure.
 
-### Above the above package directory structure
+### About the basic package directory structure
 
 Notice a few things about the above layout:
 
-1. Your package code lives within a `src/packagename` directory. While it’s fine if you wish to use a [flat layout](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#about-the-flat-python-package-layout) (a flat layout does not have a src/ directory at the root), we suggest that you use `src/` directory as it ensure you are running tests on the installed version of your code. [Learn more here.](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)
+1. Your package code lives within a `src/packagename` directory. We suggest that you use `src/` directory as it ensure you are running tests on the installed version of your code. However, you are welcome to instead use a [flat layout](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#about-the-flat-python-package-layout) which does not have a src/ directory at the root. [Learn more here.](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html#the-src-layout-and-testing)
 2. Within the `src/` directory you have a package directory called `pyospackage/`. Use the name of your package for that directory name.
 3. In your package directory, you have an `__init__.py` file and all of your Python modules.
 4. The `pyproject.toml` file lives at the root directory of your package.
@@ -241,7 +248,7 @@ instance, a `build-system` table most often holds 2 variables:
 
 TOML organizes data structures, defining relationships within a configuration
 file. You will learn more about the `pyproject.toml` format in the
-[next lesson when you add additional metadata / information to this file.](3-pyproject-toml.md)
+[next lesson when you add additional metadata / information to this file.](5-pyproject-toml.md)
 
 ```toml
 # An example of the build-system table which contains two variables - requires and build-backend
@@ -437,6 +444,8 @@ level vs. what makes the most sense to keep in individual modules.
 
 :::{important}
 
+TODO: We had a bit of discussion in slack about this and i'd like to
+get more feedback via a review before fleshing this section out more. i'm still unclear on when this should be taught and what guidelines to provide as to when to surface functionality in a package...
 > TODO: Guidelines for when and how to add methods and such to the `__init__.py` file here.
 
 > `__all__ = ['add_num']`
@@ -449,9 +458,9 @@ You did it! You have now created a Python package that you can install into any
 
 In the upcoming lessons you will:
 
-* add a [README file](2-add-readme.md) and [LICENSE ](3-add-license-file.md) to your package
-* [Add more metadata to your `pyproject.toml`](3-pyproject-toml.md) file to support PyPI publication.
-* [Learn how to build your your package distribution](4-publish-pypi.md) files (**sdist** and **wheel**) and
+* add a [README file](2-add-readme.md) and [LICENSE ](4-add-license-file.md) to your package
+* [Add more metadata to your `pyproject.toml`](5-pyproject-toml.md) file to support PyPI publication.
+* [Learn how to build your your package distribution](6-publish-pypi.md) files (**sdist** and **wheel**) and
 publish to **test PyPI**.
 * Finally you will learn how to publish to conda-forge from PyPI.