Merge pull request #182 from UC-Davis-molecular-computing/dev

Dev

.github/workflows/run_unit_tests.yml

@@ -20,8 +20,8 @@ jobs:
       uses: s-weigand/setup-conda@v1
       with:
         activate-conda: true
-    - name: Install xlwt with conda
-      run: conda install xlwt=1.3.0
+    - name: Install xlwt and xlrd with conda
+      run: conda install xlwt=1.3.0 xlrd=2.0.1
     - name: Install docutils with conda
       run: conda install docutils=0.16
     - name: Test with unittest

.gitignore

@@ -7,6 +7,8 @@ __pyache__/*
 *.egg-info
 /scadnano.zip
 .pypirc
+tests/tests_outputs/
+tests/tests_outputs/cadnano_v2_export/*
 tests/tests_outputs/cadnano_v2_export/test_16_helix_origami_rectangle_no_twist.dna
 tests/tests_outputs/cadnano_v2_export/test_16_helix_origami_rectangle_no_twist.json
 tests/tests_outputs/cadnano_v2_export/test_2_stape_2_helix_origami_deletions_insertions.dna

CONTRIBUTING.md

@@ -7,7 +7,13 @@ or post questions as issues on the [issues page](https://github.com/UC-Davis-mol
 
 
 
+## Table of contents
 
+* [What should I know before I get started?](#what-should-i-know-before-i-get-started)
+* [Cloning](#cloning)
+* [Pushing to the repository dev branch and documenting changes (done on all updates)](#pushing-to-the-repository-dev-branch-and-documenting-changes-done-on-all-updates)
+* [Pushing to the repository main branch and documenting changes (done less frequently)](#pushing-to-the-repository-main-branch-and-documenting-changes-done-less-frequently)
+* [Styleguide](#styleguide)
 
 
 
@@ -54,10 +60,8 @@ We use [git](https://git-scm.com/docs/gittutorial) and [GitHub](https://guides.g
 
 
 
-## Making Contributions
 
-
-### Cloning
+## Cloning
 
 The first step is cloning the repository so you have it available locally.
 
@@ -82,15 +86,15 @@ git checkout dev
 
 
 
-### Pushing to the repository dev branch and documenting changes (done on all updates)
+## Pushing to the repository dev branch and documenting changes (done on all updates)
 
 Minor changes, such as updating README, adding example files, etc., can be committed directly to the `dev` branch. (Note: currently this option is only available to administrators; other contributors should follow the instructions below.)
 
 For any more significant change that is made (e.g., closing an issue, adding a new feature), follow these steps:
 
 1. If there is not already a GitHub issue describing the desired change, make one. Make sure that its title is a self-contained description, and that it describes the change we would like to make to the software. For example, *"problem with importing gridless design"* is a bad title. A better title is *"fix problem where importing gridless design with negative x coordinates throws exception"*.
 
-2. Make a new branch specifically for the issue. Base this branch off of `dev` (**WARNING**: in GitHub desktop, the default is to base it off of `master`, so switch that). The title of the issue (with appropriate hyphenation) is a good name for the branch. (In GitHub Desktop, if you paste the title of the issue, it automatically adds the hyphens.)
+2. Make a new branch specifically for the issue. Base this branch off of `dev` (**WARNING**: in GitHub desktop, the default is to base it off of `main`, so switch that). The title of the issue (with appropriate hyphenation) is a good name for the branch. (In GitHub Desktop, if you paste the title of the issue, it automatically adds the hyphens.)
 
 3. If it is about fixing a bug, *first* add tests to reproduce the bug before working on fixing it. (This is so-called [test-driven development](https://www.google.com/search?q=test-driven+development))
 
@@ -102,7 +106,7 @@ For any more significant change that is made (e.g., closing an issue, adding a n
 
 7. Commit the changes. In the commit message, reference the issue using the phrase "fixes #123" or "closes #123" (see [here](https://docs.github.com/en/enterprise/2.16/user/github/managing-your-work-on-github/closing-issues-using-keywords)). Also, in the commit message, describe the issue that was fixed (one easy way is to copy the title of the issue); this message will show up in automatically generated release notes, so this is part of the official documentation of what changed.
 
-8. Create a pull request (PR). **WARNING:** by default, it will want to merge into the `master` branch. Change the destination branch to `dev`.
+8. Create a pull request (PR). **WARNING:** by default, it will want to merge into the `main` branch. Change the destination branch to `dev`.
 
 9. Wait for all checks to complete (see next section), and then merge the changes from the new branch into `dev`. This will typically require someone else to review the code first and possibly request changes.
 
@@ -118,13 +122,13 @@ For any more significant change that is made (e.g., closing an issue, adding a n
 
 
 
-### Pushing to the repository master branch and documenting changes (done less frequently)
+## Pushing to the repository main branch and documenting changes (done less frequently)
 
-Less frequently, pull requests (abbreviated PR) can be made from `dev` to `master`, but make sure that `dev` is working before merging to `master` as all changes to `master` are automatically built and deployed to [PyPI](https://pypi.org/project/scadnano/), which is the site hosting the pip installation package, and [readthedocs](https://scadnano-python-package.readthedocs.io/en/latest/), which is the site hosting the API documentation. That is, changes to master immediately affect users installing via pip or reading online documention, so it is critical that these work.
+Less frequently, pull requests (abbreviated PR) can be made from `dev` to `main`, but make sure that `dev` is working before merging to `main` as all changes to `main` are automatically built and deployed to [PyPI](https://pypi.org/project/scadnano/), which is the site hosting the pip installation package, and [readthedocs](https://scadnano-python-package.readthedocs.io/en/latest/), which is the site hosting the API documentation. That is, changes to main immediately affect users installing via pip or reading online documentation, so it is critical that these work.
 
 **WARNING:** Always wait for the checks to complete. This is important to ensure that unit tests pass. 
 
-We have an automated release system (through a GitHub action) that automatically creates release notes when changes are merged into the master branch.
+We have an automated release system (through a GitHub action) that automatically creates release notes when changes are merged into the main branch.
 
 Although the GitHub web interface abbreviates long commit messages, the full commit message is included for each commit in a PR.
 
@@ -140,27 +144,27 @@ Breaking changes should be announced explicitly, perhaps in the commit message,
 
 See here for an example: https://github.com/UC-Davis-molecular-computing/scadnano-python-package/releases/tag/v0.10.0
 
-So the steps for committing to the master branch are:
+So the steps for committing to the main branch are:
 
 1. If necessary, follow the instructions above to merge changes from a temporary branch to the `dev` branch. There will typically be several of these. Despite GitHub's suggestions to keep commit messages short and put longer text in descriptions, because only the commit message is included in the release notes, it's okay to put more detail in the message (but very long stuff should go in the description, or possibly documentation such as the README.md file).
 
     One of the changes committed should change the version number. We follow [semantic versioning](https://semver.org/). This is a string of the form `"MAJOR.MINOR.PATCH"`, e.g., `"0.9.3"`
-    - For the web interface repo scadnano, this is located at the top of the file https://github.com/UC-Davis-molecular-computing/scadnano/blob/master/lib/src/constants.dart
-    - For the Python library repo scadnano-python-package, this is located in two places: the bottom of the file https://github.com/UC-Davis-molecular-computing/scadnano-python-package/blob/master/scadnano/_version.py (as `__version__ = "0.9.3"` or something similar) and the near the top of the file https://github.com/UC-Davis-molecular-computing/scadnano-python-package/blob/master/scadnano/scadnano.py (as `__version__ = "0.9.3"` or something similar). This latter one is only there for users who do not install from PyPI, and who simply download the file scadnano.py to put it in a directory with their script).
+    - For the web interface repo scadnano, this is located at the top of the file https://github.com/UC-Davis-molecular-computing/scadnano/blob/main/lib/src/constants.dart
+    - For the Python library repo scadnano-python-package, this is located in two places: the bottom of the file https://github.com/UC-Davis-molecular-computing/scadnano-python-package/blob/main/scadnano/_version.py (as `__version__ = "0.9.3"` or something similar) and the near the top of the file https://github.com/UC-Davis-molecular-computing/scadnano-python-package/blob/main/scadnano/scadnano.py (as `__version__ = "0.9.3"` or something similar). This latter one is only there for users who do not install from PyPI, and who simply download the file scadnano.py to put it in a directory with their script).
 
     The PATCH version numbers are not always synced between the two repos, but, they should stay synced on MAJOR and MINOR versions. **Note:** right now this isn't quite true since MINOR versions deal with backwards-compatible feature additions, and some features are supported on one but not the other; e.g., modifications can be made in the Python package but not the web interface, and calculating helix rolls/positions from crossovers can be done in the web interface but not the Python package. But post-version-1.0.0, the major and minor versions of the  should be enforced.
 
 3. Ensure all unit tests pass.
 
-4. In the Python repo, ensure that the documentation is generated without errors. From the subfolder `doc`, run the command `make html`, ensure there are no errors, and inspect the documentation it generates in the folder `build`.
+4. In the Python repo, ensure that the documentation is generated without errors. First, run `pip install sphinx sphinx_rtd_theme`. This installs [Sphinx](https://www.sphinx-doc.org/en/main/), which is the most well-supported documentation generator for Python. (It's not very friendly, the syntax for things like links in docstrings is awkward, but it's well supported, so we use it.) Then, from within the subfolder `doc`, run the command `make html` (or `make.bat html` on Windows), ensure there are no errors, and inspect the documentation it generates in the folder `_build`.
 
-5. Create a PR to merge changes from dev into master. 
+5. Create a PR to merge changes from dev into main. 
 
 6. One the PR is reviewed and approved, do the merge.
 
 7. Once the PR changes are merged, a release will be automatically created here: https://github.com/UC-Davis-molecular-computing/scadnano/releases or https://github.com/UC-Davis-molecular-computing/scadnano-python-package/releases. It will have a title that is a placerholder, which is a reminder to change its title and tag. Each commit will be documented, with the commit message (but not description) included in the release notes.
 
-8. Change *both* the title *and* tag to the version number with a `v` prepended, e.g., `v0.9.3`. It is imperative to change the tag before the next merge into master, or else the release (which defaults to the tag `latest`) will be overwritten.
+8. Change *both* the title *and* tag to the version number with a `v` prepended, e.g., `v0.9.3`. It is imperative to change the tag before the next merge into main, or else the release (which defaults to the tag `latest`) will be overwritten.
 
 
 

README.md

@@ -17,6 +17,8 @@ If you find scadnano useful in a scientific project, please cite its associated
   DNA 2020: *Proceedings of the 26th International Conference on DNA Computing and Molecular Programming*  
   [ [paper](https://doi.org/10.4230/LIPIcs.DNA.2020.9) | [BibTeX](https://web.cs.ucdavis.edu/~doty/papers/scadnano.bib) ]
 
+*Note:* If you are reading this on the PyPI website, some of the links below won't work. Many are relative links intended to be read on the [GitHub README page](https://github.com/UC-Davis-molecular-computing/scadnano-python-package#readme).
+
 
 ## Table of contents