Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Small spelling and grammar fixes #106

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions LICENSING_GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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/)

Expand All @@ -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

Expand Down
4 changes: 2 additions & 2 deletions PYTHON_CODING.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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.

Expand Down
6 changes: 3 additions & 3 deletions STRUCTURING_YOUR_PROJECT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions VERSION_CONTROL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand Down