Skip to content

Commit ec30452

Browse files
stainstain
authored
Merge pull request #169 from common-workflow-language/documentation
Developer Documentation
2 parents 8e0d99a + ac95a7b commit ec30452

File tree

3 files changed

+199
-0
lines changed

3 files changed

+199
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Contributing
2+
Thank you for taking an interest in contributing to CWL Viewer.
3+
4+
The following is a set of guidelines for contribution and helpful
5+
tips and resources for working with the code base.
6+
7+
## Code of Conduct
8+
This project and everyone participating in it is governed by
9+
the [CWL Project Code of Conduct](https://github.com/common-workflow-language/common-workflow-language/blob/master/CODE_OF_CONDUCT.md).
10+
By participating, you are expected to uphold this code.
11+
Please report unacceptable behavior to
12+
[[email protected]](mailto:[email protected]).
13+
14+
## Issue Contribution
15+
Issues for both bug reports and feature requests are welcome. In
16+
the case of bug reports, please try to provide a verifiable example
17+
on the production instance if this is possible.
18+
19+
Before you submit an issue, please search the issue tracker, maybe
20+
an issue for your problem already exists and the discussion might
21+
inform you of workarounds readily available.
22+
23+
## Code Contribution
24+
25+
### Workflow
26+
The preferred workflow for contributing to CWL Viewer is to fork the
27+
[main repository](https://github.com/common-workflow-language/cwlviewer) on
28+
GitHub, clone, and develop on a branch. Steps:
29+
30+
1. Fork the [project repository](https://github.com/common-workflow-language/cwlviewer)
31+
by clicking on the 'Fork' button near the top right of the page. This creates
32+
a copy of the code under your GitHub user account. For more details on
33+
how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).
34+
35+
2. Clone your fork of the cwlviewer repo from your GitHub account to your local disk:
36+
37+
```bash
38+
$ git clone [email protected]:YourLogin/cwlviewer.git
39+
$ cd cwlviewer
40+
```
41+
42+
3. Create a ``feature`` branch to hold your development changes:
43+
44+
```bash
45+
$ git checkout -b my-feature
46+
```
47+
48+
Always use a ``feature`` branch. It's good practice to never work on the ``master`` branch!
49+
50+
4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files:
51+
52+
```bash
53+
$ git add modified_files
54+
$ git commit
55+
```
56+
57+
to record your changes in Git, then push the changes to your GitHub account with:
58+
59+
```bash
60+
$ git push -u origin my-feature
61+
```
62+
63+
5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork)
64+
to create a pull request from your fork.
65+
66+
### Running the Application and Tests
67+
See [README.md](README.md) for details on running the application with dependencies.
68+
The tests can be run using the standard `mvn test` command.
69+
70+
### Code Structure and Dependencies
71+
This project uses the [Maven standard directory layout](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
72+
and is a [Model-view-controller](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)
73+
application built with [Spring Boot](https://projects.spring.io/spring-boot/).
74+
75+
Packaging is done by feature and all Spring configuration is
76+
Java annotation based.
77+
78+
Templates for the view use [Thymeleaf](http://www.thymeleaf.org/),
79+
which allows them to be displayed in browsers as static prototypes.
80+
81+
MongoDB is used to store information about `Workflow` and `QueuedWorkflow`
82+
objects using [Spring Data JPA](https://docs.spring.io/spring-data/mongodb/docs/current/reference/html/).
83+
84+
The application also uses a triple store to keep the RDF representing
85+
workflows (gathered from [cwltool](https://github.com/common-workflow-language/cwltool)'s
86+
`--print-rdf` functionality).
87+
88+
In general, the controller classes call services which have the main logic for
89+
the application. These controllers are:
90+
* `PageController` - handles basic static pages such as the index and documentation
91+
* `workflow.WorkflowController` - the main controller class for the application
92+
* `workflow.WorkflowJSONController` - handles API functionality
93+
* `workflow.PermalinkController` - handles permalinks with content negotiation for
94+
retrieving different formats
95+
96+
Notable services include
97+
* `workflow.WorkflowService` - Handles workflow related functionality
98+
* `researchobject.ROBundleService` - Creates research object bundles
99+
* `graphviz.GraphVizService` - A wrapper for `com.github.jabbalaci.graphviz.GraphViz`
100+
to generate images from DOT source code
101+
* `git.GitService` - Builds on JGit to provide Git functionality
102+
* `cwl.CWLService` - Implements parsing of cwl files
103+
104+
Note: For the async operations, Spring does not support the calling of a method within
105+
the same class (as a proxy needs to kick in to spawn a new thread). For this reason
106+
some extra classes such as `researchobject.ROBundleFactory` and `cwl.CWLToolRunner`
107+
are used when they would otherwise not be required.
108+
109+
### Basic Application Flow
110+
111+
1. User fills in the form on the front page. This is represented by
112+
`workflow.WorkflowForm` and consists of just a URL to Github/Gitlab,
113+
or a URL to a git repository as well as the branch and path of a
114+
workflow within the repository.
115+
116+
2. This is submitted and picked up by a method in `workflow.WorkflowController`.
117+
The form is validated and parsed by `workflow.WorkflowFormValidator` to
118+
produce a `git.GitDetails` object with a repository URL, branch and path.
119+
The MongoDB database is checked for already pending `workflow.QueuedWorkflow` or
120+
created `workflow.Workflow` objects based on this (but this flow assumes they do
121+
not already exist).
122+
123+
3. A new `workflow.QueuedWorkflow` object is created by cloning the repository
124+
locally (if it does not already exist), checking out the new branch and parsing
125+
the file using built-in YAML parsing code. Intermediate visualisations and
126+
models are produced which may not yet be complete.
127+
128+
4. [cwltool](https://github.com/common-workflow-language/cwltool) is run on the
129+
workflow using the `--print-rdf` option to produce the RDF representation. The RDF
130+
will be stored in the SPARQL store and queries will extract the information
131+
required. Afterwards this is used to construct a Research Object Bundle for the workflow.
132+
This is an asynchronous operation so meanwhile...
133+
134+
5. The user is redirected to the main workflow page, which will use the `loading`
135+
template for now until cwltool has finished running. The background is the intermediate
136+
visualisation. An AJAX call repeatedly checks the status of cwltool saved in the
137+
`workflow.QueuedWorkflow` object in MongoDB.
138+
139+
6. The page either displays an error on the loading page or reloads to view the
140+
parsed workflow on the `workflow` template. An AJAX call checks if the Research Object
141+
Bundle has been created and adds it to the page when it has.

‎ISSUE_TEMPLATE.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<!--- Provide a general summary of the issue in the Title above -->
2+
3+
## Description
4+
<!--- Provide a more detailed introduction to the issue itself, and why you consider it to be a bug -->
5+
6+
## Expected Behavior
7+
<!--- Tell us what should happen -->
8+
9+
## Actual Behavior
10+
<!--- Tell us what happens instead -->
11+
12+
## Possible Fix
13+
<!--- Not obligatory, but suggest a fix or reason for the bug -->
14+
15+
## Steps to Reproduce
16+
<!--- Provide a link to a live example, or an unambiguous set of steps to -->
17+
<!--- reproduce this bug. Include code to reproduce, if relevant -->
18+
1.
19+
2.
20+
3.
21+
4.
22+
23+
## Context
24+
<!--- How has this bug affected you? What were you trying to accomplish? -->
25+
26+
## Your Environment
27+
<!--- Include as many relevant details about the environment you experienced the bug in -->
28+
* Version used:
29+
* Environment name and version (e.g. Chrome 39, Java 1.8):

‎PULL_REQUEST_TEMPLATE.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<!--- Provide a general summary of your changes in the Title above -->
2+
3+
## Description
4+
<!--- Describe your changes in detail -->
5+
6+
## Motivation and Context
7+
<!--- Why is this change required? What problem does it solve? -->
8+
<!--- If it fixes an open issue, please link to the issue here. -->
9+
10+
## How Has This Been Tested?
11+
<!--- Please describe in detail how you tested your changes. -->
12+
<!--- Include details of your testing environment, and the tests you ran to -->
13+
<!--- see how your change affects other areas of the code, etc. -->
14+
15+
## Screenshots (if appropriate):
16+
17+
## Types of changes
18+
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
19+
- [ ] Bug fix (non-breaking change which fixes an issue)
20+
- [ ] New feature (non-breaking change which adds functionality)
21+
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
22+
23+
## Checklist:
24+
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
25+
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
26+
- [ ] My change requires a change to the documentation.
27+
- [ ] I have updated the documentation accordingly.
28+
- [ ] I have added tests to cover my changes.
29+
- [ ] All new and existing tests passed.

0 commit comments

Comments
 (0)