diff --git a/source/common.rst b/source/common.rst index 908f5f0..8623fcf 100644 --- a/source/common.rst +++ b/source/common.rst @@ -586,7 +586,7 @@ collaborators inside SO, or the general public, or both? Releases and Release Numbering ============================== -When releasing a new version of your code, we reccomend to use the "Release" +When releasing a new version of your code, we recommend to use the "Release" feature of Github from the main branch of your repository. This will create a tag and also automatically generate a release page. It will also allow you to trigger a CI workflow to build and upload your code to a package repository @@ -619,7 +619,7 @@ new features or fix a significant number of issues to the code, without changing the API. In the case of releases that are primarily bug fixes or rolling releases, the patch version z should be incremented. -Specifics of how to implement semantic versioning, such as `versionneer` and +Specifics of how to implement semantic versioning, such as `versioneer` and `cmake-git-version-tracking`, in your code is included in the specific documentation of each programming language. @@ -639,7 +639,7 @@ workflow). The goal is to catch regressions quickly and to give developers confidence that individual components are correct before combining them. -All codeabases regardless of programming language should include unit tests. +All codebases regardless of programming language should include unit tests. Designing good unit tests ------------------------- diff --git a/source/copyright.rst b/source/copyright.rst index 391ac42..44a0acc 100644 --- a/source/copyright.rst +++ b/source/copyright.rst @@ -103,7 +103,7 @@ provided that any of the following is true: - SO controls the copyright of the code. - The code is openly licensed. - The code is not openly licensed, but a specific license has been - obtained that will grant the neccessary rights over the necessary + obtained that will grant the necessary rights over the necessary time period. In contrast to "Openly Contributed Code", we defined "Specially diff --git a/source/docs.rst b/source/docs.rst index a1474c3..82662eb 100644 --- a/source/docs.rst +++ b/source/docs.rst @@ -2,7 +2,7 @@ Code Documentation ================== -This section deals with standards and tools for code documention. +This section deals with standards and tools for code documentation. This includes inline comments as well as more narrative works that stand alone (perhaps in a web page or PDF) to provide reference, tutorial, or background information on code operation or usage. diff --git a/source/intro.rst b/source/intro.rst index d402f73..19fa5a3 100644 --- a/source/intro.rst +++ b/source/intro.rst @@ -23,7 +23,7 @@ Why have a Developer's Guide and Style Guide? Code, especially open source code, is a collaborative effort. In addition, we all have our own coding styles and preferences, and that's a good thing. Furthermore, software code is a product that is distributed to the public and hopefully will be used by many -people outside of the collaboration. Incosistent code styles makes it harder for +people outside of the collaboration. Inconsistent code styles makes it harder for contributors and users to read, understand and reuse code. A developer and style guide aims to lower this friction. @@ -36,8 +36,8 @@ small, focused, and easier on maintainers to review. A developer guide goes further: it captures the institutional knowledge that experienced SO developers carry in their heads. Which testing framework do we use? How should a -new package be structured? Writing these decisions down means a new collaborator can be -productive in as little time as possble. +new package be structured? Writing these decisions down means a new collaborator can be +productive in as little time as possible. The purpose of the guide is not to enforce uniformity just for the sake of uniformity. Rather to reduce the time needed for new contributors to get up to speed, and reduce diff --git a/source/python.rst b/source/python.rst index fa29d38..9bed273 100644 --- a/source/python.rst +++ b/source/python.rst @@ -77,7 +77,7 @@ variable. We will utilize the following naming conventions: #. Class and struct names should be in PascalCase, e.g. `MyClass`. -#. Function names should be in camelCase, e.g. `myFunction`. +#. Function names should be in snake_case, e.g. `my_function`. #. Variable names should be in snake_case, e.g. `my_variable`. #. Constants should be in ALL_CAPS with underscores, e.g. `MAX_SIZE`. #. Modules and submodules should be in snake_case, e.g. `my_module`. @@ -86,7 +86,7 @@ We will utilize the following naming conventions: Typing ------ -Python typing is optional, but we recommend to use it in all new code. It provides +Python typing is optional, but we recommend to use it in all new code. It provides a way to document the expected types of a function's arguments and return value. We also suggest when used to use the `typing` module of the standard library, and not a third part library. Please refer to `PEP 484`_ for more information. @@ -153,7 +153,7 @@ We will accept any standard that meets the following criteria: We strongly recommended that SO codes uses the `numpy style`_ as it is widely used in scientific Python packages, from numpy to astropy. You can also use the `google style`_ for docstrings, but you need to be clear -about it in either the README or CONITRIBUTING file. These two styles are +about it in either the README or CONTRIBUTING file. These two styles are very similar. They are both supported in Sphinx, e.g. through the `napoleon plugin`_. @@ -496,7 +496,7 @@ output, type coercion, and a consistent interface for users:: Declare scripts as ``scripts`` in ``pyproject.toml`` so that ``pip install`` places them on the user's ``PATH`` automatically: -.. code-block::toml +.. code-block:: toml [project.scripts] my-tool = "mypackage.cli:main" @@ -542,7 +542,7 @@ Automatic Semantic Versioning There are several tools and methods to automatically generate version numbers for Python packages. Three of the most popular are `versioneer`_, -`setuptools_scm`_ and `hatchling`_. +`setuptools_scm`_ and `hatch-vcs`_. Versioneer ---------- @@ -636,7 +636,7 @@ To get versioneer operating on your python project, do the following: .. _click: https://click.palletsprojects.com/ .. _versioneer: https://github.com/python-versioneer/python-versioneer/tree/master .. _setuptools_scm: https://github.com/pypa/setuptools-scm/blob/main/setuptools-scm/README.md -.. _hatchling: https://pypi.org/project/hatchling/ +.. _hatch-vcs: https://github.com/ofek/hatch-vcs/ .. _pytest: https://docs.pytest.org/ .. _pybind11: https://pybind11.readthedocs.io/ .. _Cython: https://cython.readthedocs.io/