diff options
Diffstat (limited to 'processing')
| -rw-r--r-- | processing/chapter.tex | 172 |
1 files changed, 134 insertions, 38 deletions
diff --git a/processing/chapter.tex b/processing/chapter.tex index 1ec2c37..997b297 100644 --- a/processing/chapter.tex +++ b/processing/chapter.tex @@ -1084,44 +1084,31 @@ dataset—it’s really useful for inspecting the quality of your fit procedure. \section{Construction, maintenance, and distribution} % ==========================================
While WrightTools has already been useful to the work done in the WrightGroup over the last 3
-years, the true potential of the package is in potential future uses. %
-WrightTools is designed to be extended and continuously enhanced to serve an ever-wider set of
-users and spectroscopies. %
-Despite it's name, WrightTools is built to be used even by those outside of the Wright Group. %
+years, the true potential of the package lies in its future. %
+WrightTools is designed in a modular way so that it can be continuously enhanced to serve an
+ever-wider set of users and spectroscopies. %
+Despite its name, WrightTools is built to be used even by those outside of the Wright Group. %
Currently WrightTools may be only 75\% of what a typical multidimensional spectroscopist needs, but
if those scientists work to enhance the package with what \emph{they} need, they may also solve
problems for others such that the usefulness of the software gradually increases. %
In order for this dream to come true, WrightTools must be constructed and maintained by
collaborative tools such that users feel comfortable contributing to future enhancements. %
-It has not been easy to build this software as a group of 3 to 5 contributors, and the coordination
-problems will be harder as more users and developers join. %
-To this end, the following section discusses strategies for keeping WrightTools collaborative and
-useful. %
+All of the challenges to collaboration discussed in \autoref{cha:sof} certainly apply to
+WrightTools, so it is important that we follow best practices now in order to make WrightTools as
+maintainable and future-proof as possible. %
+To this end, this section discusses strategies that I have employed in the construction,
+maintenance, and distribution of WrightTools. %
\subsection{Licensing} % ------------------------------------------------------------------------
-In order to even talk about collaborative development, one must at least have an open source
-license. %
-According to US copyright law, software is fully copyright protected by default. % TODO: cite
+As discussed in \autoref{cha:sof}, open source licenses are an important part of scientific
+software development. %
Those writing software must explicitly license their project in order to ensure that users have
basic rights to copy edit and distribute code. %
-A whole set of licenses have been written to use for this purpose. %
-Briefly, strong copyleft licenses do not allow for software to be modified or enhancements without
-sharing those enhancements under the same licenses. %
-These ``viral'' licenses are meant to force companies and individuals who would otherwise not open
-source to share their code. %
-The strongest copyleft licenses do not even allow others to link against the licensed software
-without themselves being copyleft. %
-This strategy has been moderately successful, but is becoming less popular. % TODO: cite
-Open source licenses are less opinionated, merely granting users the right to copy, modify,
-distribute, and publish code without restriction except perhaps credit to the source. %
-
-% TODO: link GPL, LGPL etc
-
-WrightTools is MIT licensed (otherwise called the Expat license). %
+WrightTools is licensed under the hugely popular Expat/MIT license. %
This license is incredibly permissive and puts as few restrictions as possible on the end users. %
-Because the license is short, it is reproduced below. %
+The following is the WrightTools license, reproduced in its entirety. %
\begin{dquote}
@@ -1154,30 +1141,139 @@ However many Python libraries end up being interfaces to compiled code that coul closed-source. %
The Scientific Python Stack have MIT-compatible licenses, including BSD-like licenses. %
-\subsection{Distribution} \label{pro:sec:distribution} % ------------------------------------------
+\subsection{Version control} % -------------------------------------------------------------------
+
+As mentioned several times in \autoref{cha:sof}, having software under source control is probably
+the most important recommendation in scientific software development. %
+Source control allows developers to create ``checkpoints'' for their software package that can be
+returned to again and again. %
+Developers can collaborate together to edit the software by making incremental changes that are
+easy to review. %
+
+WrightTools uses git \cite{git} for source control, and the package is hosted on GitHub
+\cite{GitHub, WrightToolsGitHub}. %
+As of 2018-04-08, WrightTools has 1,018 commits from seven developers, as shown in
+\autoref{pro:tab:commits}. %
+In addition to simply hosting the git repo, GitHub gives us issue tracking and automated
+integration with zenodo. %
+
+The WrightTools package has a developer controlled version as well, following the semantic
+versioning convention \cite{SemanticVersioning}. %
+The current distributed version of WrightTools is \bash{3.0.1}, with \bash{3.0.2} under active
+development. %
+The wt5 file also has a semantic version, currently \bash{1.0.0}. %
+These attributes can be accessed through python: \python{wt.__version__} and
+\python{wt.__wt5_version__}. %
-How does WrightTools get onto end-users machines? %
-Distribution...
+\begin{table}
+ \begin{tabular}{c | c | c | c}
+ person & number of commits & lines added & lines removed \\ \hline
+ Blaise Thompson & 478 & 621,918 & 507,938 \\ \hline
+ Kyle Sunden & 208 & 19,293 & 9,218 \\ \hline
+ Darien Morrow & 29 & 1,589 & 127 \\ \hline
+ Nathan Neff-Mallon & 20 & 2,880 & 910 \\ \hline
+ Kyle Czech & 5 & 1,150 & 25 \\ \hline
+ Daniel Kohler & 3 & 113 & 29 \\ \hline
+ Rachel Swedin & 1 & 5,197 & 0 \\ \hline
+ \end{tabular}
+ \caption[CAPTION TODO]{
+ Commits to WrightTools by individual, ordered by number of commits.
+ Wright Stuff is...
+ Note that datasets...
+ }
+ \label{pro:tab:commits}
+\end{table}
-WrightTools is distributed on PyPI and conda-forge. %
+\subsection{Unit tests} % ------------------------------------------------------------------------
-WrightTools uses semantic versioning. %
+Maintainable code must be tested, so that future developers can use tests to ensure that they do
+not break necessary functionality. %
+Unit testing is a very simple testing paradigm in which small, separate tests are written to
+address each ``unit'' of the software package. %
+As an example, the following is one of WrightTools' tests:
+\begin{codefragment}{python}
+# part of WrightTools/tests/data/convert_data.py
+def test_wigner():
+ p = datasets.COLORS.v2p2_WL_wigner
+ data = wt.data.from_COLORS(p)
+ assert data.d1.units == 'fs'
+ data.convert('ns')
+ assert data.d1.units == 'ns'
+ assert data.wm.units == 'nm'
+ data.close()
+\end{codefragment}
+This test loads one of the distributed COLORS datasets and makes sure that the \python{convert}
+method works as intended. %
+To do this, it uses the \python{assert} statement which raises an exception when a condition is
+\python{False}. %
+This particular test is pretty humble, but there is strength in numbers: as of 2018-04-08 there are
+224 unit tests within WrightTools. %
+Using the built in \python{pytest} library (\bash{python setup.py test}), a programmer can run all
+of the tests and receive a report on what failed and why. %
+If a future programmer unintentionally breaks \python{convert}, the above test will fail and alert
+her to the unexpected side effect of her modification. %
+
+[PARAGRAPH ABOUT CONTINUOUS INTEGRATION]
-% TODO: citations to WrightTools on PyPI and conda-forge
+\subsection{Distribution} \label{pro:sec:distribution} % ------------------------------------------
+
+WrightTools is on GitHub, which is a fantastic way for developers to get software onto their
+computers. %
+But how does software get onto everybody elses machine? %
+Developers call this process ``distribution''. %
+Luckily for us, distribution is fairly simple within the Python ecosystem. %
+The same tools that are used to distribute hugely popular packages like numpy are also available
+for anyone else, including WrightTools. %
+
+The Python Package Index (PyPI), affectionately known as the cheese shop, is the official third
+party software repository for Python. %
+It is community maintained, and supported by the Python Software Foundation and The Python
+Packaging Group. %
+As of 2018-04-08 PyPI hosts 134,758 Python packages, all for free. %
+WrightTools is also hosted on PyPI. %
+Every time we change our version, we ``release'' by uploading the newest version to PyPI. %
+pip (``pip installs packages'', ``pip installs python'', or ``preferred installer program'') [CITE]
+can be used to install packages directly from PyPI: %
+\begin{codefragment}{bash}
+pip install WrightTools
+\end{codefragment}
+
+Conda is a multilingual package manager that handles virtual environments and dependencies, even
+binary dependencies, in a hassle-free way. %
+Since the scientific Python ecosystem has so many non-Python binary dependencies, Conda is a
+popular choice---especially on Windows where the necessary compilers are not typically
+pre-installed. %
+Unlike pip, conda is not tied to a single repository. %
+There is the official repository, maintained by Anaconda, the company that develops conda.
+[CITE] %
+There is also the popular conda-forge repository, which is maintained by the community via
+GitHub. [CITE] %
+WrightTools is on conda-forge: %
+\begin{codefragment}{bash}
+conda config --add channels conda-forge
+conda install WrightTools
+\end{codefragment}
-\subsection{Collaborative development} % ---------------------------------------------------------
+\subsection{Documentation} % ---------------------------------------------------------------------
-Git...
+WrightTools is a piece of scripted software, and many spectroscopists many not be comfortable with
+using such a thing immediately. %
+To this end, it is important to have easy to use, searchable documentation with end-users in
+mind. %
-As of 2018-04-08, WrightTools has ........ commits from ..... developers
+wright.tools
-\subsection{Unit tests} % ------------------------------------------------------------------------
+Built and hosted by readthedocs
-Unit testing...
+Both master and development versions...
\clearpage
\section{Future directions} % ====================================================================
Single variable decomposition. %
-Usage in next-generation simulation packages. %
\ No newline at end of file +Usage in next-generation simulation packages. %
+
+More tests. %
+
+Usage by multiple groups. %
\ No newline at end of file |