Skip to content

Commit

Permalink
improve model archival guidance
Browse files Browse the repository at this point in the history 
- add help link to the model upload tutorial on forum.comses.net from
@chyhuang
- add initial text guidance on the relationship between code and data
and docs and where we place files + caveat
- switch archival package filesystem layout from a modal to an
always-displayed card, revisit this as needed

fixes #390
  • Loading branch information
@alee
alee committed Feb 4, 2019
1 parent 3318879 commit fa263a1
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 49 deletions.
8 changes: 2 additions & 6 deletions frontend/src/pages/codebase/release/detail.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,13 @@ export const schema = yup.object().shape({
document how to run your computational model, software and data dependencies, accepted inputs and expected
outputs.
</p>
<p>
<small class='text-muted'><em>NOTE: We will be updating this process soon to help us build containerized versions of your
computational models - stay tuned!</em></small>
</p>
<c-markdown v-model="release_notes" :errorMsgs="errors.release_notes" name="releaseNotes" rows="3"
label="Release Notes" :required="config.release_notes">
</c-markdown>
<c-datepicker v-model="embargo_end_date" :errorMsgs="errors.embargo_end_date" name="embargoEndDate" :clearButton="true"
:required="config.embargo_end_date"
label="Embargo End Date"
help="If this release is currently private, a date when your release will be automatically published">
help="The date your private release will be automatically made public">
</c-datepicker>
<div :class="['form-group', {'child-is-invalid': errors.os.length > 0}]">
<label :class="['form-control-label', {'required': config.os}]">Operating System</label>
Expand All @@ -55,7 +51,7 @@ export const schema = yup.object().shape({
@input="updateOs"
name="os"
:options="osOptions"
placeholder="The operating system and version this model has been developed and tested on, e.g., Ubuntu 18.04 or Windows 10"
placeholder="The operating system this model has been developed and tested on, e.g., Ubuntu, Mac, or Windows"
label="display"
track-by="name">
</multiselect>
Expand Down
77 changes: 37 additions & 40 deletions frontend/src/pages/codebase/release/upload.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,28 +46,20 @@ class FileTree extends Vue {
@Component(<any>{
template: `<div>
<p class='mt-3'>
Releases should include all code, documentation, input data and simulation results necessary for someone
else (including your future self) to understand or reuse the model. Source code is required.
A codebase releases should include all code, documentation, input data and simulation results necessary for
someone else (including your future self) to understand or reuse the model. Source code is required. Please take
note of the directory structure that we use for your uploaded files - in particular, data files are uploaded to a
<code>project-root/data</code> directory so if your source code has references to your uploaded data files you
should consider using the relative path <code>../data/&lt;datafile&gt;</code>. This will make the lives of others
who want to download and run your model easier.
</p>
<button class="btn btn-secondary" @click="showPreview">Preview Download Package</button>
<div class="modal fade" id="previewModal" tabindex="-1" role="dialog" aria-labelledby="previewModalLabel">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="previewModalLabel">Release File Download Preview</h5>
<button type="button" class="close" @click="closePreview" aria-label="Close">
<span aria-hidden="true" class="fa fa-times"></span>
</button>
</div>
<div class="modal-body">
<span class="text-warning" v-if="folderContents === null">Loading download preview...</span>
<div class="alert alert-danger" v-else-if="folderContents.error !== undefined">
{{ folderContents.error }}
</div>
<c-file-tree :directory="folderContents" v-else></c-file-tree>
</div>
</div>
<div class="card card-body bg-light">
<h3 class='card-title'>Current Archival Package Filesystem Layout</h3>
<span class="text-warning" v-if="folderContents === null">Loading download preview...</span>
<div class="alert alert-danger" v-else-if="folderContents.error !== undefined">
{{ folderContents.error }}
</div>
<c-file-tree :directory="folderContents" v-else></c-file-tree>
</div>
<div v-for="config in configs">
<c-upload :uploadType="config.uploadType" :acceptedFileTypes="config.acceptedFileTypes"
Expand All @@ -93,27 +85,34 @@ export class UploadPage extends Vue {
uploadType: 'code',
acceptedFileTypes: '*/*',
title: 'Upload Source Code',
instructions: `You can upload a single plaintext source file (e.g., NetLogo) or zipped archive of plaintext
source code (currently accepting zip or tar files) representing your codebase. Archives will be unpacked and
extracted as part of archival processing and system files will be removed but the archive's directory
structure is preserved. All file types are accepted though they should be in open or plaintext formats.`,
originalInstructions: 'Submitted source code file.',
instructions: `You can upload a single plaintext source file (e.g., a NetLogo .nlogo file) or a tar or zip archive of
plaintext source code representing your codebase. Archives will be unpacked and extracted as part of archival processing
and system files will be removed but the archive's directory structure is preserved. All file types are currently
accepted though files should be stored in open or plaintext formats. We may remove executables or binaries in the
future.`,
originalInstructions: 'Submitted source code file(s):',
},
{
uploadType: 'data',
acceptedFileTypes: '*/*',
title: 'Upload Data',
instructions: `Upload any data associated with your source code. If an archive (zip or tar file) is uploaded
it is extracted first. Files should be plaintext or open data formats but all file types are accepted.`,
originalInstructions: 'Submitted data files.'
instructions: `Upload any datasets required by your source code. There is a limit on file upload size so if
your datasets are very large, you may consider using osf.io or figshare or other data repository to store your
data and refer to it in your code via DOI or other permanent URL. If a zip or tar archive is uploaded
it will be automatically unpacked. Files should be plaintext or an open data formats but all file types
are currently accepted. Please note that data files uploaded here will be placed in a "<project-root>/data"
directory so if you'd like for your source code to work immediately when another researcher downloads your
codebase, please consider referring to any input data files via a relative path "../data/<your-data-file>".`,
originalInstructions: 'Submitted data file(s):'
},
{
uploadType: 'docs',
acceptedFileTypes: '*/*',
title: 'Upload Narrative Documentation',
instructions: `Upload narrative documentation (e.g., the ODD Protocol) that comprehensively describes your
computational model. Acceptable files include plain text formats (e.g., Markdown, Jupyter Notebooks,
ReStructuredText), OpenDocument Text (ODT), or PDF`,
instructions: `Upload narrative documentation that comprehensively describes your computational model. The ODD
Protocol offers a good starting point for thinking about how to comprehensively describe agent based models and
good Narrative Documentation often includes equations, pseudocode, and flow diagrams. Acceptable files include
plain text formats (including Markdown and other structured text), OpenDocument Text files (ODT), and PDF documents.`,
originalInstructions: 'Submitted narrative documentation files.'
},
{
Expand All @@ -133,19 +132,14 @@ export class UploadPage extends Vue {
return this.$store.state.release.codebase.identifier;
}

showPreview() {
(<any>$)('#previewModal').modal('show');
created() {
this.getDownloadPreview();
}

closePreview() {
(<any>$)('#previewModal').modal('hide');
this.folderContents = null;
}

async getDownloadPreview() {
const response = await codebaseReleaseAPI
.downloadPreview({ identifier: this.identifier, version_number: this.version_number});
const response = await codebaseReleaseAPI.downloadPreview(
{ identifier: this.identifier, version_number: this.version_number}
);
if (response.data) {
this.folderContents = response.data;
} else {
Expand All @@ -164,14 +158,17 @@ export class UploadPage extends Vue {
}

doneUpload(uploadType: string) {
this.getDownloadPreview();
return this.$store.dispatch('getOriginalFiles', uploadType);
}

deleteFile(uploadType: string, path: string) {
this.getDownloadPreview();
this.$store.dispatch('deleteFile', {category: uploadType, path});
}

clear(uploadType: string) {
this.getDownloadPreview();
this.$store.dispatch('clearCategory', {
identifier: this.identifier, version_number: this.version_number,
category: uploadType
Expand Down
11 changes: 8 additions & 3 deletions frontend/src/pages/codebase/release/workflow.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -224,8 +224,14 @@ class PublishModal extends createFormValidator(publishSchema) {
},
template: `<div>
<div v-if="isInitialized">
<h1>{{ $store.state.release.codebase.title }} <i>v{{ $store.state.release.version_number }}</i></h1>
<h5 class="text-muted">Review Status: {{ reviewStatus }} | <a :href='absolute_url'>View Live</a></h5>
<h1>
<span v-if='! isPublished' title='This release is currently private and unpublished.' class="disabled btn btn-warning"><i class='fa fa-lock'></i> Private</span>
{{ $store.state.release.codebase.title }} <i>v{{ $store.state.release.version_number }}</i>
</h1>
<h5 class="text-muted">
Peer Review Status: {{ reviewStatus }} | <a :href='absolute_url'>View Live</a>
<a class='float-right' href='//forum.comses.net/t/archiving-your-model-1-getting-started/7377'><i class='fa fa-question-circle'></i> Need help? Check out our archiving tutorial</a>
</h5>
<div class='pb-2'>
<span class="btn btn-primary" data-target="#editCodebaseModal" data-toggle="modal"><i class='fa fa-edit'></i> Edit Common Metadata | Add Images &amp; Media</span>
<div class='float-right'>
Expand All @@ -234,7 +240,6 @@ class PublishModal extends createFormValidator(publishSchema) {
<span class="disabled btn btn-info" v-if="isPublished"><i class='fa fa-share-alt'></i> Published</span>
<span v-else>
<span class="btn btn-danger" data-target="#publishCodebaseReleaseModal" data-toggle="modal"><span class='fa fa-share-alt'></span> Publish</span>
<span class="disabled btn btn-info"><i class='fa fa-lock'></i> Private</span>
</span>
</div>
</div>
Expand Down

0 comments on commit fa263a1

Please sign in to comment.