From c9c7d69a5e770cbeaccdced8f3c61227161f09b6 Mon Sep 17 00:00:00 2001 From: Jake Anderson Date: Mon, 5 Dec 2022 01:32:40 -0800 Subject: [PATCH 1/4] Spelling & linkrot --- LICENSING_GUIDELINES.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/LICENSING_GUIDELINES.md b/LICENSING_GUIDELINES.md index bf6e541..fa971a4 100644 --- a/LICENSING_GUIDELINES.md +++ b/LICENSING_GUIDELINES.md @@ -4,7 +4,7 @@ When starting a new software project, there are many questions, from goals and m A critical detail is often glossed over: the license terms. Explicitly specifying a license that gives your users permission to use, modify, and distribute your work is an important part of the process of reproducible science; without explicitly specifying a license that describes how your work may be used, you may inadvertently greatly limit the impact of your work because copyright and related law restricts how others can use it. -While licenses may see to be complex (and boring) legal documents, fortunately, several open source licenses are both widely used by the community and easy to understand. +While licenses may seem to be complex (and boring) legal documents, fortunately, several open source licenses are both widely used by the community and easy to understand. To describe them, we'll separate licenses into two categories: * [__Permissive__](https://en.wikipedia.org/wiki/Permissive_software_licence): Places no restriction on the use of the code in derivative works, including commercialization. Often only requires citation. @@ -101,7 +101,7 @@ While incentivizing further open source development indeed is a worthy goal, it ### GPL -Possibly one of the most well-known copyleft licenses, the GPL, or GNU General Public License, places strong conditions on developers of derivative works. Derivative works must not only be open-source, but must also carry the a compatible license, giving it a "viral" property. So, why would you use this license? If you want to make sure that useful derivatives of your work are freely available to other developers, this may be an appropriate license. +Possibly one of the most well-known copyleft licenses, the GPL, or GNU General Public License, places strong conditions on developers of derivative works. Derivative works must not only be open-source, but must also carry a compatible license, giving it a "viral" property. So, why would you use this license? If you want to make sure that useful derivatives of your work are freely available to other developers, this may be an appropriate license. As the GPL is quite lengthy, we have not reproduced it here, but you may find a fuller description [on this page](http://choosealicense.com/licenses/gpl-3.0/) @@ -124,7 +124,7 @@ While the GPL and LGPL are intended to ensure that users of code can access the ### Dual license What if you like the idea of the GPL, but also have commercial partners interested in your code but not the GPL? Or what if your scientific collaborators have written incompatible code? -It is important to recall that as the developer, you may re-license the code to a group without these restrictions. For a scientific example, the Folding@Home project distributes a binary of a modified version of [GROMACS](http://gromacs.org) that includes cryptographic code to prevent tampering or altering scientific results on donor machines; Folding@Home [obtained a special license](https://foldingathome.stanford.edu/support/faq/opensource/) from the GROMACS developers for this purpose, even though GROMACS was then a GPL-licensed software package (and now LGPL-licensed). +It is important to recall that as the developer, you may re-license the code to a group without these restrictions. For a scientific example, the Folding@Home project distributes a binary of a modified version of [GROMACS](http://gromacs.org) that includes cryptographic code to prevent tampering or altering scientific results on donor machines; Folding@Home [obtained a special license](https://foldingathome.org/support/faq/opensource) from the GROMACS developers for this purpose, even though GROMACS was then a GPL-licensed software package (and now LGPL-licensed). ### Changing the license From 9343e85f0fc6311f9d274066198810120f4fe851 Mon Sep 17 00:00:00 2001 From: Jake Anderson Date: Mon, 5 Dec 2022 01:37:04 -0800 Subject: [PATCH 2/4] Spelling --- STRUCTURING_YOUR_PROJECT.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/STRUCTURING_YOUR_PROJECT.md b/STRUCTURING_YOUR_PROJECT.md index ff864c2..b51adc4 100644 --- a/STRUCTURING_YOUR_PROJECT.md +++ b/STRUCTURING_YOUR_PROJECT.md @@ -13,7 +13,7 @@ pip install cookiecutter cookiecutter gh:molssi/cookiecutter-cms ``` You can then answer the questions posed to create a new project that will automatically -be checked into a new local git repo, and is ready to be pushed to [GitHub](http://github.com). +be checked into a new local git repo, and it is then ready to be pushed to [GitHub](http://github.com). Below, we review the basic philosophy behind how the [CMS Cookiecutter](https://github.com/MolSSI/cookiecutter-cms) structures a new repository and why. @@ -54,7 +54,7 @@ setup.py ``` This list may appear daunting at first, but each element is either a critical component of what will make the software -easy to access, and easy to maintain. The following sections will break down each element in the skeleton and explain +easy to access and maintain. The following sections will break down each element in the skeleton and explain why they are helpful. Your package may not need *every* element of this skeleton, but should include many of them. ## The root directory: Primary setup file, CI control, and Git(Hub) Helpers @@ -93,7 +93,7 @@ The `README.md` file is the *most important file* for a GitHub project. A Markdo by GitHub on the project's homepage. That means this is the **FIRST** thing users see when visiting `exampleproject`, so this should be an informative file which tells users the following: 1. Short explanation of what the project does -1. Quick "How-To install and run" the project. This should be only a few lines, which is why its important to +1. Quick "How-To install and run" the project. This should be only a few lines, which is why it's important to ensure the project can be installed easily. * This topic is covered [in a later chapter][package_deploy_page], but its important to plan for this section now 1. Who the authors of the package are From 644e6b946cba52112c7aa61beb37a0648fbc2b73 Mon Sep 17 00:00:00 2001 From: Jake Anderson Date: Mon, 5 Dec 2022 01:42:19 -0800 Subject: [PATCH 3/4] Spelling --- VERSION_CONTROL.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/VERSION_CONTROL.md b/VERSION_CONTROL.md index 93f273a..22a51da 100644 --- a/VERSION_CONTROL.md +++ b/VERSION_CONTROL.md @@ -42,7 +42,7 @@ If you create your project using the [MolSSI CMS Cookiecutter](https://github.co ### For existing projects -You may already have a codebases that uses a different version control system. +You may already have a codebases that use a different version control system. A very popular version control software is Subversion (`svn`). It may be worth investing the effort to switch to `git`. While `git` has a slightly steeper learning curve, you may find the features it offers worth it. @@ -65,7 +65,7 @@ People also often consider Mercurial to be easier to learn. Unless you have good reason not to, use [GitHub](http://github.com). GitHub makes collaboration on code very easy, and for small groups it offers unlimited private repositories (should you need them; we don't recommend using private repos unless it's absolutely essential to protect data of collaborators). -At the same time, it allows you to publish and share your completed projects with the open source community, to increase the impact of your code, and allow for contributions from the community. +At the same time, it allows you to publish and share your completed projects with the open source community, increase the impact of your code, and allow for contributions from the community. There are many integrations for GitHub that allow you to automatically test your code, assess the code quality, and host documentation, which makes the development even easier. Recently, [GitHub Actions](https://github.com/features/actions) have been added to make this even easier. @@ -78,7 +78,7 @@ opened to discuss the merge with the main branch of the repository. This is a gr of the code for projects that have few developers, and a small codebase. Alternatively, on GitHub, opening a pull-request from a fork is just as easy, and it is the preferred way of having -outside collaborators contribute to the codebase. This helps keeping the main code separate, while allowing other +outside collaborators contribute to the codebase. This helps keep the main code separate, while allowing other developers to experiment. Even within the same company or group, you may find that using forks lowers the barrier for development. It is a workflow worth considering. @@ -102,9 +102,9 @@ are built against. This is a model which is good for a small number of developers which all have write access to the repository. This is also the recommended model for your own projects to mitigate possible damage to the `master` branch, which can be very hard to fix. -1. Create a new branch on your local copy, lets call it `awesome_new_feature` +1. Create a new branch on your local copy, let's call it `awesome_new_feature` 2. Make your changes to the code - * *Pitfall Warning:* You can make changes before switching branches, but this often leads you to committing directly + * *Pitfall Warning:* You can make changes before switching branches, but this often leads you to commit directly to master, which is difficult to fix 3. Commit your changes 4. Test locally, repeat previous two steps as needed @@ -119,7 +119,7 @@ This is also the recommended model for your own projects to mitigate possible da This example is slightly different than the previous model and is better for repositories with many possible contributors without write access to the repository, such as users who want to propose bug fixes or features. The -limited write access, but accepted pull requests from forks encourages user contribution while still retaining +limited write access, but accepted pull requests from forks encourage user contribution while still retaining tight control of the code base. 1. [Fork a repository][github_fork] into your personal account From b407544919f5cbb1fdb2294aee092c7ea11bbd1e Mon Sep 17 00:00:00 2001 From: Jake Anderson Date: Mon, 5 Dec 2022 01:45:41 -0800 Subject: [PATCH 4/4] Spelling --- PYTHON_CODING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PYTHON_CODING.md b/PYTHON_CODING.md index 6945cfb..a9fa2d7 100644 --- a/PYTHON_CODING.md +++ b/PYTHON_CODING.md @@ -1,6 +1,6 @@ # Python coding best practices -You are writing code that you and other people (and future you!) will read and modify multiple times, so there are few things to keep in mind that will simplify your life: +You are writing code that you and other people (and future you!) will read and modify multiple times, so there are a few things to keep in mind that will simplify your life: - **Keep it simple, clean, and documented.** Your code and your documentation are your best methods section! Write it so that your colleagues can understand it easily. This may mean the difference between being able to easily understand and reuse your own code six months from now and having to rewrite everything from scratch. - **Make it robust and extensible.** Writing robust code means you will spend less time debugging, or even worse, analyzing results from an incorrect code. Writing extensible code means you will spend less time modifying it. @@ -37,7 +37,7 @@ The document is not the most exciting read, but the good news is __you don't hav PyCharm has this feature enabled by default. For Atom, simply install the [linter-pep8](https://atom.io/packages/search?q=pep8) package. -[Black](https://github.com/psf/black) is the uncompromising Python code formatter. It formats your code so as to comply with most of pep8 requirements except the fact it does not help you with naming convention. In a team context, it enforces a common and pep8 compliant coding styles. +[Black](https://github.com/psf/black) is the uncompromising Python code formatter. It formats your code so as to comply with most of pep8 requirements except the fact it does not help you with naming convention. In a team context, it enforces common and pep8 compliant coding styles. [iSort](https://github.com/PyCQA/isort) a Python utility / library to sort imports alphabetically, and automatically separated into sections and by type. It makes your import section tidy, reasonable and readable. In a team context, it makes code review easier. Because there is a single right place for your new import statement, when two people do the same imports in different location in a source file, iSort will deduplicate it.