| Age | Commit message (Collapse) | Author | Lines |
|---|
|
I attended one of Peter Wittenburg's talks in the context of RDA on the
Canonical Workflow Frameworks for Research (CWFR). Afterwards I got in
touch with him about Maneage and this paper. He kindly read the paper was
very supportive of it with positive/encouraging feedback.
It was thanks to that discussion that I added CWFR in the discussion (in
the previous commit). But since that commit was focused on IAA's
suggestions, I am acknowledging Peter here.
|
|
The AMIGA team at the Instituto Astrofísica Andalucía (IAA) are very active
proponents of reproducibility. They had already provided very constructive
comments after my visit there and many subsequent interactions. So until
now, the whole team's contributions were acknowledged.
Since the last submission, several of the team members were able to kindly
invest the time in reading the paper and providing very useful comments
which are now being implemented. As a result, I was able to specifically
thank them in the paper's acknowledgments (Thanks a lot AMIGA!). Below, I
am listing the points in the order that is shown in 'git log -p -1' for
this commit.
- Javier Moldón: "PM is not defined. First appearance in the first page".
Thanks for noticing this Javier, it has been corrected.
- Javier Moldón: "In Section III. PROPOSED CRITERIA FOR LONGEVITY and
Appendix B, you mention the FAIR principles as desirable properties of
research projects and solutions, respectively which is good, but may
bring confusion. Although they are general enough, FAIR principles are
specifically for scientific data, not scientific software. Currently,
there is an initiative promoted by the Research Data Alliance (RDA),
among others, to create FAIR principles adapted to research software, and
it is called FAIR4RS (FAIR for Research Software). More information here:
https://www.rd-alliance.org/groups/fair-4-research-software-fair4rs-wg. In
2020 there was a kick-off meeting to divide the work in 4 WG. There is
some more information in this talk:
https://sorse.github.io/programme/workshops/event-016/. I have been
following the work of WG1, and they are about the finish the first
document describing how to adapt the FAIR principles to software. Even if
all this is still work in progress, I think the paper would benefit from
mentioning the existence of this effort and noticing the diferences
between Data and Software FAIR definitions."
Thanks for highlighting this Javier, a footnote has been added for this
(hopefully faithfully summarizing it into one sentence due to space
limitations).
- Sebastian Luna Valero: "Would it be a good idea to define long-term as a
period of time; for example, 5 years is a lot in the field of computer
science (i.e. in terms of hardware and software aging), but maybe that is
not the case in other domains (e.g. Astronomy)."
Thanks Sebastian, in section 2, we do give longevity of the various
"tools" in rough units of years (this was also a suggestion by a
referee). But of course the discussion there is very generic, so going
into finer detail would probably be too subjective and bore the reader.
- Sebastian Luna Valero: "Why do you use git commit eeff5de instead of git
tags or releases for Maneage? Shown for example in the abstract of the
paper: "This paper is itself written with Maneage (project commit
eeff5de)."
Thanks for raising this important point, a sentence has been added to
explain why hashes are objective and immutable for a given history, while
tags can easily be removed or changed, or not cloned/pushed at all.
- Susana Sanchez Exposito: "We think interoperability with other research
projects would be important, do you have any plans to make maneage
interoperable with, for example, the Common Workflow Language (CWL)?".
Thanks a lot for raising this point Susana. Indeed, in the future I
really do hope we can invest enough resources on this. In the discussion,
I had already touched upon research objects as one method for
interoperability, there was also a discussion on such generic standards
in Appendix A.D.10. But to further clarify this point (given its
importance), I mentioned CWL (and also the even more generic CWFR) in the
discussion.
- Sebastian Luna Valero: "Regarding Apache Taverna, please see:"
https://github.com/apache/incubator-taverna-engine/blob/master/README.md
Thanks a lot for this note Sebastian! I didn't know this! I wrote this
section (and visited their webpage) before their "vote"! It was a
surprize to see that their page had changed. I have modified the
explanation of Taverna to mention that it has been "retired" and use the
Github link instead.
- Sebastian Luna Valero: "Page 21: 'logevity' should be 'longevity'."
Thanks a lot for noticing this! It has been corrected :-).
- Javier Moldón: "There is a nice diagram in Johannes Köster's article on
data processing with snakemake that I find very interesting to show some
key aspects of data workflows: see Fig 1 in
https://www.authorea.com/users/165354/articles/441233-sustainable-data-analysis-with-snakemake "
This is indeed a nice diagram! I tried to cite it, but as of today, this
link is not a complete paper (with no abstract and many empty section
titles). If it was complete, I would certainly have cited it in
Snakemake's discussion.
- Javier Moldón: "Regarding the problem mentioned in the introduction about
PM not precisely identified all software versions, I would like to
mention that with Snakemake, even if the analysis are usually constructed
using other package managers such as conda, or containers, you don't need
to depend on online servers or poorly-documented software versions, as
you can now encapsulate an analysis in a tarball containing all the
software needed. You still have long-term dependency problems (as you
will need to install snakemake itself, and a particular OS), but at least
you can keep the exact software versions for a particular platform."
Thanks for highlighting this Javier. This is indeed better than nothing,
we have already discussed the dangers of this "black box" approach of
archiving binaries in many contexts, and many package managers have
it. So while I really appreciate the point (I didn't know this), to avoid
lengthening the paper, I think its fine to not mention it in the paper.
|
|
Konrad had kindly gone through the paper and the appendices with very good
feedback that is now being addressed in the paper (thanks a lot Konrad!):
- IPOL recently also allows Python code. So the respective parts of the
description of IPOL have been updated. To address the dependency issue, I
also added a sentence that only certain dependencies (with certain
versions) are acceptable.
- On Active Papers (AP: which is written by Konrad) corrections were made
based on the following parts of his comments:
- "The fundamental issue with ActivePapers is its platform dependence on
either Java or Python, neither of which is attractive."
- "The one point which is overemphasized, in my opinion, is the necessity
to download large data files if some analysis script refers to it. That
is true in the current implementation (which I consider a research
prototype), but not a fundamental feature of the approach. Implementing
an on-demand download strategy is not particularly complicated, it just
needs to be done, and it wasn't a priority for my own use cases."
- "A historical anecdote: you mention that HDF View requires registering
for download. This is true today, but wasn't when I started
ActivePapers. Otherwise I'd never have built on HDF5. What happened is
that the HDF Group, formerly part of NCSA and thus a public research
infrastructure, was turned into a semi-commercial entity. They have
committed to keeping the core HDF5 library Open Source, but not any of
the tooling around it. Many users have moved away from HDF5 as a
consequence. The larger lesson is that Richard Stallman was right: if
software isn't GPLed, then you never know what will happen to it in the
future."
- On Guix, some further clarification was added to address Konrad's quote
below (with a link to the blog-post mentioned there). In short, I
clarified that I mean storing the Guix commit hash with any respective
high-level analysis change is the extra step.
- "I also looked at the discussion of Nix and Guix, which is what I am
mainly using today. It is mostly correct as well, the one exception
being the claim that 'it is up to the user to ensure that their created
environment is recorded properly for reproducibility in the
future'. The environment is *recorded* in all detail,
automatically. What requires some effort is extracting a human-readable
description of that environment. For Guix, I have described how to do
this in a blog post
(https://guix.gnu.org/en/blog/2020/reproducible-computations-with-guix/),
and in less detail in a recent CiSE paper
(https://hal.archives-ouvertes.fr/hal-02877319). There should
definitely be a better user interface for this, but it's no more than a
user interface issue. What is pretty nice in Guix by now is the user
interface for re-creating an environment, using the "guix time-machine"
subcommand."
- The sentence on Software Heritage being based on Git was reworded to fit
this comment of Konrad: "The plural sounds quite optimistic. As far as I
know, SWH is the only archive of its kind, and in view of the enormous
resources and long-time commitments it requires, I don't expect to see a
second one."
- When introducing hashes, Konrad suggested the following useful paper that
shows how they are used in content-based storage:
DOI:10.1109/MCSE.2019.2949441
- On Snakemake, Konrad had the following comment: "[A system call in Python
is] No slower than from bash, or even from any C code. Meaning no slower
than Make. It's the creation of a new process that takes most of the
time." So the point was just shifted to the many quotations necessary for
calling external programs and how it is best suited for a Python-based
project.
In addition some minor typos that I found during the process are also
fixed.
|
|
There was a single conflict in the comments of one part of 'configure.sh'
that has been fixed.
There was also a single place that needed to convert 'BDIR' to 'badir' in
this project (so after the merge, it also built easily).
|
|
Until now, the build directory contained a 'software/' directory (that
hosted all the built software), a 'tex/' subdirectory for the final
building of the paper, and many other directories containing
intermediate/final data of the specific project. But this mixing of built
software and data is against our modularity and minimal complexity
principles: built software and built data are separate things and keeping
them separate will enable many optimizations.
With this commit, the build directory of the core Maneage branch will only
contain two sub-directories: 'software/' and 'analysis/'. The 'software/'
directory has the same contents as before and is not touched in this
commit. However, the 'analysis/' directory is new and everything created in
the './project make' phase of the project will be created inside of this
directory.
To facilitate easy access to these top-level built directories, two new
variables are defined at the top of 'initialize.mk': 'badir', which is
short for "built-analysis directory" and 'bsdir', which is short for
"built-software directory".
HOW TO IMPLEMENT THIS CHANGE IN YOUR PROJECT. It is easy: simply replace
all occurances of '$(BDIR)' in your project's subMakefiles (except the ones
below) to '$(badir)'. To confirm if everything is fine before building your
project from scratch after merging, you can run the following command to
see where 'BDIR' is used and confirm the only remaning cases.
$ grep -r BDIR reproduce/analysis/*
--> make/verify.mk: innobdir=$$(echo $$infile | sed -e's|$(BDIR)/||g'); \
--> make/initialize.mk:badir=$(BDIR)/analysis
--> make/initialize.mk:bsdir=$(BDIR)/software
--> make/initialize.mk: $$sys_rm -rf $(BDIR)
--> make/top-prepare.mk:all: $(BDIR)/software/preparation-done.mk
'BDIR' should only be present in lines of the files above. If you see
'$(BDIR)' used anywhere else, simply change it to '$(badir)'. Ofcourse, if
your project assumes BDIR in other contexts, feel free to keep it, it will
not conflict. If anything un-expected happens, please post a comment on the
link below (you need to be registered on Savannah to post a comment):
https://savannah.nongnu.org/task/?15855
One consequence of this change is that the 'analysis/' subdirectory can be
optionally mounted on a separate partition. The need for this actually came
up for some new users of Maneage in a Docker image. Docker can fix
portability problems on systems that we haven't yet supported (even
Windows!), or had a chance to fix low-level issues on. However, Docker
doesn't have a GUI interface. So to see the built PDF or intermediate data,
it was necessary to copy the built data to the host system after every
change, which is annoying during working on a project. It would also need
two copies of the source: one in the host, one in the container. All these
frustrations can be fixed with this new feature.
To describe this scenario, README.md now has a new section titled "Only
software environment in the Docker image". It explains step-by-step how you
can make a Docker image to only host the built software environment. While
your project's source, software tarballs and 'BDIR/analysis' directories
are on your host operating system. It has been tested before this commit
and works very nicely.
|
|
With the submission of the revision (which highlighted all the relevant
parts to the points the referees raised in the submitted PDF) it is no
longer necessary to highlight these parts.
If we get another revision request, we can add new '\new' parts for
highlighting.
|
|
This commit makes some minor fixes following the hardwired non-numerical
solution to the cross-referencing issue between the main article and the
supplement, such as fixing "lineage like lineage" and missing closing
parentheses.
From Mohammad: while re-basing the commit over the 'master' branch, I also
added Boud'd name at the top of the copyright holders of the appendices.
|
|
Until now, when building GNU Binutils on GNU Linux operating systems, we
would simply put a link to the host's core C library components (the
'*crt*' files). However, the symbolic link wasn't "forced"! So if it
already existed in the build directory, it would crash.
With this commit a '-f' option has been added to the 'ln' command and this
fixed the problem.
This bug was reported by Zahra Sharbaf.
|
|
Since the addition of the appendix bibliography we hadn't checked the 'make
dist' command, as a result the PDF couldn't be built. With this commit, in
the 'dist' rule, we are now also copying 'appendix.bbl' and the created
tarball could build the PDF properly. Also the 'peer-review' directory is
now also included in the tarball created by './project make dist'.
I also found a small typo in the description of Occam (an 'a' was missing)
and fixed it.
|
|
In preparation for the submission of the revised manuscript, I went through
the full paper and appendices one last time. The second appendix (reviewing
existing reproducible solutions) in particular needed some attention
because some of the tools weren't properly compared with the criteria.
In the paper, I was also able to remove about 30 words, and bring our own
count (which is an over-estimation already) to below 6250.
|
|
Given the new appendix/supplement structure, it was necessary to go through
the answers and correct them. I also generally edited them and added a
top-level letter to the editors (to directly copy-paste into the webpage).
|
|
There weren't any conflicts in this merge; either technical conflicts that
can be found by Git, or logical conflicts (that will cause a crash in the
project).
|
|
After correctly setting Less to depend on 'ncurses', I noticed its still
not linking to Maneage's 'ncurses', but pointing to my host system's
'ncurses' (that happens to have the same version! So it would crash on a
system with a different version). This shows that like some other software,
we need to manually correct the RPATH inside Less.
With this command, the necessary call to 'patchelf' has been added and with
it, the installed 'less' command properly linked to Maneage's internal
build of 'ncurses'.
|
|
After going through the publication checklist, some edits were made to make
things more clear. Also, an item was added to remind the project author
that the commit hashes on the uploaded data files should be the same.
|
|
Until now, the description in 'README.md' to build the Dockerfile in
'README.md' had one item per line, thoroughly describing the reason behind
that line. But in many cases, the user is already familiar with Docker (or
has already read through the items) and just wants to have the Dockerfile
ready fast. In these cases, all those extra explanations are annoying.
With this commit, an item '0' has been added at the start of the item list
for summary. It only contains the necessary Dockerfile contents with no
extra explanation.
|
|
Until now, the 'less' software package (used to view large files easily on
the command-line and used by Git for things like 'git diff' or 'git log')
only depended on 'patchelf' (which is a very low-level software).
However, as Boud reported in bug #59811 [1], building less would crash with
an error saying "Cannot find terminal libraries" in some systems (including
the proposed Docker image of 'README.md' which I confirmed
afterwards). Looking into the 'configure' script of 'less', I noticed that
'less' is actually just checking for some functions provided by the ncurses
library!
With this commit, 'less' depends on 'ncurses'. I was able to confirm that
with this change, 'less' successfully builds within the Docker image.
[1] https://savannah.nongnu.org/bugs/?59811
|
|
After his previous two commits, we discussed some of the points and I am
making these edits following those. In particular the last statement about
Madagascar "could have been more useful..." was changed to simply mention
that mixing workflow with analysis is against the modularity principle. We
should not judge its usefulness to the community (which is beyond our scope
and would need an official survey).
A few other minor edits were done here and there to clarify some of the
points.
|
|
With this commit, I have corrected some minor typos of this appendix.
They are very minor corrections.
|
|
With this commit, I have corrected some minor typos of this appendix.
In addition to that, I also put empty lines to separate subsections and
subsubsections appropiately.
|
|
I ran a simple Emacs spell check over the main body and the two
appendices. All discovered typos have been fixed.
|
|
With this commit, I have corrected some minor typos of this appendix. In
addition to that, I also put empty lines to separate subsections and
subsubsections appropiately (5 lines and 1 line, respectively).
|
|
With this commit, I had a look at the paper and correct some minor typos.
When possible, I tried to simplify some phrases to have less number of words.
To do that, I added some hypens when I considered it could be necessary/possible.
|
|
Having entered 2021, it was necessary to update the years of all the
copyright statements.
|
|
There were only three very small conflicts that have been fixed.
|
|
Until now, in the appendices we were simply using '\ref' to refer to
different parts of the published paper. However, when built in
'--supplement' mode, the main body of the paper is a separate PDF and
having links to a separate PDF is not impossible, but far too complicated.
However, having the links adds to the richness of the text and helps point
readers to specific parts of the paper.
With this commit, there is a LaTeX conditional anywhere in the appendices
that we want to refer the reader to sections/figures in the main body. When
building a separate PDF, the resepective section/figure is cited in a
descriptive mode (like "Seciton discussing longevity of tools"). However,
when the appendices go into the same PDF as the main body, the '\ref's
remain.
|
|
Having added/modified text in the supplements, Boud is now a copyright
holder of this file too.
I also added 2021 to the copyright years of paper.tex and supplement.tex.
|
|
This commit does some minor copyediting, especially of the
introduction to the supplement. There's no point complaining to
the reader about the word limit of the journal: s/he is not
interested in that. This is not the right place for discussing
journal policy. The need for summarising content and focussing on
key elements of a cohesive argument is fundamental in a world of
information overload. A&A/MNRAS/ApJ/PRD letters are generally
much worse than normal articles in terms of reproducibility
because they have to omit so many details that the reader has
to read the full articles to really know what is done. But the
reality is that letters get read a lot, because they're short
and snappy.
|
|
In the abstract the repeated benefits of Maneage (which are also mentioned
in the criteria) were removed to fit into CiSE's online submission
guidelines. In Section II (Longevity of existing tools), the paragraph that
itemized the following paragrahs as a numbered list has been removed with
the sentence that repeatedly states the importance of reproducibility in
the sciences and some branches of the industry.
With these changes our approximate automatic count has 6277 words. This is
still very slightly larger than the 6250 word limit of the
journal. However, this count is a definite over-estimation (including many
things like page titles and page numberings from the raw PDF to text
conversion). So the actual count for the journal publication should be less
than this.
A few other tiny corrections were made:
- The year of the paper and copyright in 'README.md' was set to 2021. The
copyright of the rest of the files will be set to 2021 after the next
merge with Maneage soon (the years of core infrastructure copyrights has
already been corrected there).
- Mohammadreza's name was added in 'README.md'.
- The line to import the "necessity" appendix has been commented in the
version to have the full paper in one PDF (to be upladed to arXiv or
Zenodo).
- The supplement PDF now starts with '\appendices' so the sections have
the same labels as the single-PDF version.
|
|
Until now the supplement had no introduction for a random reader to see the
purpose of this "Web extra" supplement.
With this commit, an abstract has been added.
|
|
Until now, the build strategy of the paper was to have a single output PDF
that either contains (1) the full paper with appendices in the same paper
(2) only the main body of the paper with no appencies.
But the editor in chief of CiSE recently recommended publishing the
appendices as supplements that is a separate PDF (on its webpage). So with
this commit, the project can make either (1) a single PDF (containing both
the main body and the appendices) that will be published on arXiv and will
be the default output (this is the same as before). (2) two PDFs: one that
is only the main body of the paper and another that is only the appendices.
Since the appendices will be printed as a PDF in any case now, the old
'--no-appendix' option has been replaced by '--supplement'. Also, the
internal shell/TeX variable 'noappendix' has been renamed to
'separatesupplement'.
|
|
Until now there was only a 'clean' (to delete all files created during the
'make' phase) and the 'distclean' (to delete all files during configuration
and make). But sometimes we don't want to delete all the files created
during the full 'make' phase, we only want to delete the files that were
created by LaTeX for building the paper.
Witht this commit, a new target has been added for this job. You can now
run the following command for this job:
./project make texclean
Only the files in '$(BDIR)/tex/build' will be deleted (and the 'tikz'
directory under that location is recreated, ready for a future build).
|
|
Having entered 2021, it was necessary to update the copyright years at the
top of the source files. We recommend that you do this for all your
project-specific source files also.
|
|
Since we have a long list of Copyright statements at the top, I thought its
easier to just move the copyright notice to the top of 'paper.tex' also.
In the acknowledgments, the paragraph on Maneage was slighltly summarized
to save a few words and still be clear. Also, the long name of the Japanese
Ministry of Education, Culture, Sports, Science, and Technology, was
summarized to Japanese MEXT.
In the biographies, the '-at' (replacing '@' in the emails) was changed to
'-AT' to be more clear to the eye that its just a place holder.
|
|
As recommended by Lorena Barba (editor in chief of CiSE), we should prepare
the appendices as a separate "Supplement" for the journal. But we also want
them to be appendices within the paper when built for arXiv.
As a first step, with this commit, each appendix has been put in a separate
'tex/src/appendix-*.tex' file and '\input' into the paper. We will then be
able to conditionally include them in the PDF or not.
Also, as recommended by Lorena, the general "necessity for reproducible
research" appendix isn't included (possibly going into the webpage later).
|
|
After adding Mohammadreza as an author of the paper, we forgot to add him
as a copyright holder at the start of the paper.
|
|
This commit makes many small wording fixes, mainly to Appendix A.
It also insert "quotes" around some of the titles fields in
'tex/src/references.tex', since otherwise capitalisation is lost (DNA
becomes Dna; 'of Reinhart and Rogoff' becomes 'of reinhart and rogoff'; and
so on). I didn't do this for all titles, because some Have All Words
Capitalised, which blocks the .bib file from choosing a consistent style.
|
|
Mohammadreza has made significant contributions to the text of the paper
and also the source. However his contributions to the text came after the
initial submission, so until now, he was not added as an author. The reason
we waited for this was that no responses were given by CiSE editors, on the
inquiry of the possibility of adding a new author at this phase.
With this commit, following approval from the editors, Mohammadreza's
information has been added to the manuscript as an author to refrain from
delays in submitting the manuscript revision.
While merging with the 'master' branch, Mohammad also done some minor edits
to the other biographies to follow a similar format.
|
|
Some minor edits were made to the paper to shorten it. In particular the
example of IPOL was removed from the main body of the paper, and we'll just
rely on the more extensive review of IPOL in the appendix. I also updated
the referee report to account for the new Appendix A that is just an
extended introduction.
Also, I noticed that the Menke+20 paper that we replicate here has recently
been published in the iScience journal. So its bibliography was updated
from the bioarXiv information to the journal information.
Also, the number of words (after removing abstract and captions and
accounting for figures) is now only printed when the project is built with
'--no-appendix'. This was done because this information is
extra/annoying/unnecessary for the case where there is an appendix.
|
|
In the first/long draft of this work, we had a good introduction on the
necessity of reproducibility. But we were forced to remove it because of
word-count limits. Having moved a major portion of the previous work into
the appendices, I thought it would be good to put that introduction as a
first appendix also, focused on the necessity for reproducibile research.
|
|
Following Boud's point in the previous commit, I tried to clarify the point
in the text that we are only talking about hand-written source files: in
short, in this part of the paper, we are not talking abou the
version/snapshot for arXiv which needs figures and many extra automatically
built files. We are just talking about the raw, hand-written files. Trying
to convince people how good it is to keep the raw files separate from
automatically generated files ;-).
Also, while looking around in other parts of the main body of the paper, I
tried to edit/clarify a few points and summarize/shorten others.
|
|
This commit fixes 'automaticly', 'mega byte', 'terra byte'.
It also changes 'will be far less than a mega byte' to 'should be
less than a megabyte'. The reason for 'should' is that in some
cases, providing a small data set in the package is useful, as in
[1]. Of course, [1] would be only 0.9 Mb in size, including the
data sets, instead of 1.3 Mb, if the author, whoever that may
happen to be, had excluded the useless (produced) file
'paper-tmp.eps'. :P Case [2] is 0.4 Mb.
These two tar archives are for ArXiv, so they also contain
produced .eps files. So maybe in principle 'far less than'
is right. However, on neither [3] nor [4], trying to follow
the recommendations :), are any of the "useful" versions of
single file archives smaller than the ArXiv version. The
git bundles are bigger because of the git history, and the
'software' archives are 0.5 to 0.6 Gb because they include
almost everything.
However, stating something that is possible in principle but
not done in practice would be misleading. So I would not include
'far less'.
[1] https://zenodo.org/record/3951152/files/subpoisson-252cf1c-arXiv.tar.gz
[2] https://zenodo.org/record/4062461/files/elaphrocentre-724a7c8-arXiv.tar.gz
[3] https://zenodo.org/record/3951152
[4] https://zenodo.org/record/4062461
|
|
This commit fixes the labels alliez19, claerbout1992, schwab2000
which were multiply defined. The problem was using \citeappendix
instead of \cite for these in the appendix, even though they
are first used in the official part of the article.
You must do './project make clean' before recreating the pdf
in order for this to compile correctly. (Otherwise you'll waste
time re-using old files; this means that one of our 'make'
dependencies could in principle be improved.)
With this change, these references in the pdf are (for me)
correct clickable links back to [5], [1], [11], respectively.
[If you use xpdf (poppler library), remember the 'b' key for
navigate back from a clicked internal link quickly.]
This way you can quickly navigate between the appendix text
and the references used, and you avoid LaTeX warning about
'multiply defined labels'.
|
|
This commit provides a little bit of minor copyediting, mainly in
the appendices, based on and around changing the casual 'isn't',
'don't' and other contractions with 'not' to a less casual style
of language. A few of the changes aim to improve the meaning in
tiny ways.
|
|
The sentence sounds better with 'the'.
|
|
It was recently announced by both RedHat[1] and CentOS[2] that CentOS 8
(which was meant to end LTS at 2030) will be terminated 8 years early (by
the end of 2021). This is a perfect example of the longevity issues when
relying on third-party providers.
With this commit, I added this as a parenthesis after mentioning Ubuntu's
LTS web address. Some minor edits were also done in other parts of this
paragraph.
[1] https://www.redhat.com/en/blog/centos-stream-building-innovative-future-enterprise-linux
[2] https://blog.centos.org/2020/12/future-is-centos-stream
|
|
Until now, there was no warning when the 'maneage' branch didn't exist in
the Git history. This can happen when you forget to push the 'maneage'
branch to a remote for your project, and you later clone your project from
that remote (for example on another computer). We use the 'maneage' branch
to report the latest commit hash and date in the final paper (which can
greatly help future readers). Since we check the 'maneage' branch on every
run of './project make' (in 'initialize.mk') this would result in a printed
statement like this:
fatal: Not a valid object name maneage
Also until now, the description of what to do when TeXLive wasn't installed
properly wasn't complete: it didn't mention that it is necessary to delete
the TeXLive target files. This could confuse users (they would re-run
'./project configure -e', but with no effect).
With this commit, for the 'maneage' branch issue a complete warning will be
printed. Telling the user what to do to get the 'maneage' branch (and thus
fix this warning). Also, the LaTeX macros that go in the paper are now red
when the 'maneage' branch doesn't exist, telling the user to see the
printed warning (thus encouraging the user to get the branch). For the
TeXLive issue, the necessary commands to run are now also printed in the
warning.
|
|
Until now, when building the high-level (optional) software, we would give
both 'CPPFLAGS' and 'C_INCLUDE_PATH' the same value/directory in
'high-level.mk'. But we recently found that on macOS's C compiler
('clang'), if a directory is included in both 'CPPFLAGS' and
'C_INCLUDE_PATH', then that directory is ignored in 'CPPFLAGS' (which has
higher priority). This caused linking problems when the version of a
software on the host was different from the Maneage version.
With this commit, 'C_INCLUDE_PATH' is not set on macOS any more and this
fixed the problem on the reported systems.
This bug was fixed with the help of Mohammad Akhlaghi and Mahdieh Navabi.
|
|
Today, Richard Stallman sent a mail in 'info-gnu@gnu.org' (GNU's public
announcements mailing list) about proprietary obsolescence (or planned
obsolescence) [1]. After looking into it, I saw there is actually a
Wikipedia page for this concept. Since it direclty relates to our Free
software criteria, I thought its good to use this technical term there.
[1] https://www.gnu.org/proprietary/proprietary-obsolescence.html
[2] https://en.wikipedia.org/wiki/Planned_obsolescence
|
|
I just remembered that in the paragraph we compare with Jupyter, another
important point is that with based on the modularity principle, people can
choose their favorite text editor and aren't limited to one. I also tried
to remove redundant parts to avoid adding too many extra words.
|
|
Thanks a lot Boud for adding that script in your own project and linking it
here. Since the raw file (without context of the whole project) is very
hard to understand for the users, I switched the URL to the navigable URL
the link is actually on the filename. It will always show the most recent
version of this script, not the particular snapshot of now. But infact that
is better, since we can make it better and improve it over time. Maybe even
by the end of this paper's referee review will be able to include it in
Maneage's core branch.
I also removed the link to this discussion at the first paragraph of
Section IV (proof of concept). Since that is just the introduction, and
going into this level of detail there could be confusing for the
readers. Having the name of the script in the proper place is more direct
and understandable for the readers.
Thanks again Boud for the nice work on this ;-).
|
