diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..5efafaed4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest a feature to be implemented in Edirom +title: "[ftr]" +labels: 'Type: feature request' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/problem-report.md b/.github/ISSUE_TEMPLATE/problem-report.md new file mode 100644 index 000000000..c3dffd459 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/problem-report.md @@ -0,0 +1,38 @@ +--- +name: Problem report +about: Create a report to a problem +title: "[BUG]" +assignees: '' + +--- + +**Describe the problem** +A clear and concise description of what the problem is. + +**To Reproduce** +Steps to reproduce the behavior, e.g.: +1. Go to '...' [e.g. https://klarinettenquintett.weber-gesamtausgabe.de] +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Data** +Please provide a link to your data (e.g. https://github.com/Edirom/EditionExample) to see the problem or an extract of your data to reproduce the problem. + +**Edirom information** + - Version of Edirom [e.g. Release v1.0.0-beta.4 (Emeritus), see [releases](https://github.com/Edirom/Edirom-Online/releases)] + - Add any other context, that might be helpful + +**Environment information** +- Browser [e.g. Chrome, Safari, Firefox] +- Version of your MEI files [e.g. 5.0] +- Add any other context, that might be helpful + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Additional context** +Add any other context about the problem here. diff --git a/.github/images/EdiromOnline_BargheerFiedellieder_2013.jpg b/.github/images/EdiromOnline_BargheerFiedellieder_2013.jpg new file mode 100644 index 000000000..92ef084c7 Binary files /dev/null and b/.github/images/EdiromOnline_BargheerFiedellieder_2013.jpg differ diff --git a/.github/images/EdiromOnline_WeberFreischuetz_2015.jpg b/.github/images/EdiromOnline_WeberFreischuetz_2015.jpg new file mode 100644 index 000000000..f2ce99f34 Binary files /dev/null and b/.github/images/EdiromOnline_WeberFreischuetz_2015.jpg differ diff --git a/.github/images/EdiromOnline_WeberKlarinettenquintettOp34_2022.jpg b/.github/images/EdiromOnline_WeberKlarinettenquintettOp34_2022.jpg new file mode 100644 index 000000000..8c8637790 Binary files /dev/null and b/.github/images/EdiromOnline_WeberKlarinettenquintettOp34_2022.jpg differ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..d78f1945a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## Description, Context and related Issue + + + +Refs # + +## How Has This Been Tested? + + + +## Types of changes + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to change) +- [ ] Documentation Update + +## Checklist + + +- [ ] My change requires a change to the documentation. +- [ ] I have updated the documentation accordingly. +- [ ] I have performed a self-review of my code +- [ ] I have read the [CONTRIBUTING](https://github.com/Edirom/Edirom-Online/blob/develop/CONTRIBUTING.md) document. +- [ ] I have added tests to cover my changes. +- [ ] All new and existing tests passed. diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml index e88f94a7d..965e7f225 100644 --- a/.github/workflows/pre-release.yml +++ b/.github/workflows/pre-release.yml @@ -23,7 +23,9 @@ jobs: steps: - name: Chekout repository - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 + with: + submodules: 'recursive' - name: Get short sha uses: benjlevesque/short-sha@599815c8ee942a9616c92bcfb4f947a3b670ab0b # v3.0 @@ -36,7 +38,7 @@ jobs: - name: Upload Artifacts to action run if: github.repository == 'Edirom/Edirom-Online' - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3 + uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0 with: # The name that the artifact will be made available under name: EdiromOnline_${{ steps.short-sha.outputs.sha }}.zip diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..dcf292b6c --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,133 @@ + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +info@edirom.de. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e07179ce3..9c4c8f89d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,208 +1,58 @@ # Edirom Online Contributing Guidelines -# General Guidelines +- [How to contribute](#how-to-contribute) + * [Bug reports](#bug-reports) + * [Feature requests](#feature-requests) + * [Contributing code and documentation](#contributing-code-and-documentation) + + [Commit messages](#commit-messages) +- [Release Process](#release-process) +- [Versioning](#versioning) -* do not combine code-linting and content work in one commit +## How to contribute -## Whitespace handling +Edirom-Online is a free and open-source software and we appreciate to receive contributions from our community! +So first of all, thank you for considering contributing to Edirom-Online! When you do so, please try to follow these guidelines. -1. Use whitespaces, not tabs to indent code -2. Close file with a newline character +### Bug reports -# XQuery Styleguide +If you think you found a bug in Edirom-Online, first please search our [issues list](https://github.com/Edirom/Edirom-Online/issues) in case a similar issue has already been opened. If not, please [open an issue](https://github.com/Edirom/Edirom-Online/issues/new?assignees=&labels=&projects=&template=problem-report.md&title=%5BBUG%5D). We implemented a [template](https://github.com/Edirom/Edirom-Online/blob/develop/.github/ISSUE_TEMPLATE/problem-report.md) for problems and bugs to get as much information about the bug as possible, e.g. how the problem can be reproduced. Provide as much information as you can. -For formatting of XQuery files we generally rely on the basic configuration of Synchrosoft’s oXygen XML software family and its “Format & Indent” function. +### Feature requests -## xqDoc +If you think, Edirom-Online should have a feature that does not exist already, please search our [issues list](https://github.com/Edirom/Edirom-Online/issues) in case a wish for a similar feature was already reported. If not, please [open an issue](https://github.com/Edirom/Edirom-Online/issues/new?assignees=&labels=Type%3A+feature+request&projects=&template=feature_request.md&title=%5Bftr%5D) and describe the feature using our [template](https://github.com/Edirom/Edirom-Online/blob/develop/.github/ISSUE_TEMPLATE/feature_request.md) for new features. -We use [xqDoc](https://xqdoc.org) for documenting the XQueries in this repository. Please refer to the section [xqDoc Comments](https://xqdoc.org/xqdoc_comments_doc.html) of the xqDoc-website for details on formatting the documentation comment blocks. +### Contributing code and documentation -* XQuery modules must have a library module xqDoc comment preceding the module declaration. -* Function declarations must have a library module xqDoc function comment preceding the function. +If you would like to contribute to Edirom-Online developing a new feature or working on a bug fix, your contribution is highly appreciated and we kindly ask you to take the following guidelines into concern. +The active contributors have agreed to organise their work along the so-called 'git-flow-workflow' ([Driessen 2010](https://nvie.com/posts/a-successful-git-branching-model/)) to foster a clean and traceable development process. The following instructions will ensure this workflow. -## XQuery document structure +* Check the [network graph](https://github.com/Edirom/Edirom-Online/network) to see all the other forks of other persons to make sure, nobody else is already working on the topic, you want to start to address. +* Please discuss your idea first in an [issue](https://github.com/Edirom/Edirom-Online/issues). If there is no issue for your idea yet, please **open an issue**. There might be different ways to solve a problem and we want to make sure to find the right approach before spending time on a PR that cannot be merged. +* **Fork** the `Edirom/Edirom-Online` repository into your own account, e.g. `username/Edirom-Online`. (Exception: If you plan to develop in a team (only in this case!), open a dedicated branch on the Edirom-Online repository.) +* Create a **dedicated branch** for your fix or feature on your repository, e.g. `ftr-some-new-feature`. +* Make your changes, while you can commit to your branch as many times as you like. +* It is essential to **test** your modifications before committing or issuing a pull request. A recommended way is running a local eXist-db v5.3.0+ container and deploying your local build of Edirom Online together with some test-data, e.g. the [Edirom Edition Example](https://github.com/Edirom/EditionExample). For other deployment methods, please see our documentation in the [wiki](https://github.com/Edirom/Edirom-Online/wiki). +* After finishing your work, you can open a **pull request** to `Edirom/Edirom-Online` and fill in our [PR-template](https://github.com/Edirom/Edirom-Online/tree/develop/.github/pull_request_template.md) to describe what your pull request wants to implement. Make sure, that you MUST address the developer-branch. +* Each pull request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one pull request. +* Your submission will be **reviewed** afterwards. If you are asked to make changes, you can push these changes to your original branch and the pull request will be automatically updated. +* You may then delete your dedicated branch, after your pull request was merged into the `Edirom/Edirom-Online` repository. -### XQuery version declaration +#### Commit messages -```xquery -xquery version 3.1; -``` +Please make sure to provide meaningful and understandable commit messsages, that should have the following structure and content: +* `summary`: use imperative and summarize changes in around 50 characters or less, e.g. "Remove deprecated methods" +* `body`: explain what, why and how e.g. "This commit adds ... Specifically, we have added ..." +* `footer`: reference or close issues using e.g. `Refs #123, 456` or `Refs #206`or `Fixes #210` or `Closes #789` -### Beginning comments +## Release Process -For now, the beginning comments should only include the following: +Releases are discussed and declared by the Edirom community. The planned scope of features and bug fixes of upcoming releases can be read from corresponding [milestones](https://github.com/Edirom/Edirom-Online/milestones), and eventually you can also see here where contributions are most urgent needed. The Edirom community uses the functionality of Github projects to track the development of Edirom-Online using the project [Edirom Development](https://github.com/orgs/Edirom/projects/4/views/1). -```xquery -(: - : Copyright: For LICENSE-Details please refer to the LICENSE file in the root directory of this repository. - :) +The most recent 'stable' version of MEI is always found on the 'main' branch, where all releases are tagged from. The most recent 'work in progress' is found on the 'develop' branch. - ``` -The beginning comments and the structuring comments (see below) of the prolog are separated by a blank line. +## Versioning -### Prolog +The Edirom-Online Versions follow the ['semantic' versioning scheme](http://semver.org), 'X.Y.Z'. 'X' is a major release, often defined by the presence of backward-incompatible changes to the schema. 'Y' is a minor release, defined by backward compatible changes (i.e., added, but not removed, features). 'Z' is the 'patch' number, indicating a release that fixes or clarifies existing functionality. -1. The parts of the prolog, are introduced by a comment followed by a new line. -2. The below form of the comments and the order of the parts is prescriptive. -3. Each part of the prolog ends with a blank line. -```xquery -(: IMPORTS ================================================================= :) - -``` - -Sort imports by type: -1. All `import module namespace` statements registered with eXist-db -2. All `import module namespace` statements of custom modules that are not registered with eXist-db. Always use relative URIs for unregistered `import module namespace` statements. -3. Separate groups with a blank line. -4. In the groups sort alphabetically by prefix. - -```xquery -(: NAMESPACE DECLARATIONS ================================================== :) - -``` - -All `declare namespace` statements, sorted alphabetically by prefix. - -```xquery -(: OPTION DECLARATIONS ===================================================== :) - - -``` -All `declare option` statements. - -```xquery -(: VARIABLE DECLARATIONS =================================================== :) - -``` -1. Use `declare variable` statements for all required external parameters -2. All global variable declarations, i.e. `declare variable` statements. -3. Separate these two groups with a blank line. -4. In the groups, sort alphabetically. - -```xquery -(: FUNCTION DECLARATIONS =================================================== :) - -``` - -1. All `declare function` statements. -2. All function declarations have to be preceded by an xqDoc comment. -3. The xqDoc comment and function declaration belonging together are not separated by blank lines – not even one ;-) -4. The comment-function-groups are separated by blank lines. - -A prototypical example: - -```xquery -(: FUNCTION DECLARATIONS =========================================== :) - -(:~ - : - :) -declare function eg:addComment($comment as xs:string, $function as function()) -as xs:string -{ - … -} - -(:~ - :) -declare function eg:addComment($comment as xs:string, $function as function()) -as xs:string -{ - … -} -``` - -### Query body - -The Query body start after a structuring comment as follows: - -```xquery -(: QUERY BODY ============================================================== :) - -``` - -#### Strings - -Note: this is derived from the current usage in Edirom-Online code - -* escape with U+00027 APOSTROPHE: `'` - -### Literal results - -TODO: how should literal results be indented, especially when they are long, e.g., as in the case of [getAudioPlayer.xql](add/data/xql/getAudioPlayer.xql). - -### let statements - -Short variable definitions should be in a single line: - -```xquery -let $lang := 'de' -``` - -Longer assignments, especially when the contain if-else-statements or FLWOR-expressions, should break after `:=` and then indent a further level, before following the rules applicable to the respective statements, e.g.: - -```xquery -let $elems := - for $p in $participants - let $id := substring-after($p, '#') - return doc($doc)/id($id) -``` - -### Function declarations - -```xquery -(:~ - : XQdoc comment - : - … - : - :) -declare function prefix:function-name( $paramOne as datatype, §paramTwo as datatype ) -as datatype -{ - … -}; - -``` - -- [ ] at the moment return datatypes and opening curly braces of function declarations are still in the same line as the `declare function` statement -- [ ] break long function argument - -### HowTo ToDo:s - -- [ ] literal results formatting -- [ ] nested return statements -- [ ] parenthesis placement - - -# Javascript - -## AJAX calls - -The class `EdiromOnline.controller.AJAXController` provides a central method `doAJAXRequest` for performing AJAX requests. The method is provided globally as `window.doAJAXRequest`. - -`doAJAXRequest` takes the following arguments: - -* `url`: The URL of the requestet site or end point. -* `method`: The HTTP method like `PUT`, `GET`, `POST`. -* `params`: An object containing key-value-pairs of parameters for the request. -* `successFn`: A callback function which is called when the AJAX request was successfull. -* `retryNo`: The number of retries, if the requests fails. Standard is 2 retries. -* `async`: Defines the async parameter for AJAX calls. Default is 'true'. - -An example of using the function would be: - -```javascript -window.doAJAXRequest('data/xql/getAnnotationMeta.xql', - 'GET', - { - uri: uri, - lang: lang - }, - Ext.bind(function(response){ - view.setMeta(response.responseText); - }, this) -); -``` diff --git a/README.md b/README.md index 49a4b0d66..b3d3e9676 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,60 @@ -[![Build](https://github.com/Edirom/Edirom-Online/actions/workflows/docker-ci.yml/badge.svg?branch=develop&event=push)](https://github.com/Edirom/Edirom-Online/actions/workflows/docker-ci.yml) +[![Build](https://github.com/Edirom/Edirom-Online/actions/workflows/docker-ci.yml/badge.svg?branch=develop&event=push)](https://github.com/Edirom/Edirom-Online/actions/workflows/docker-ci.yml) [![NFDI4C Registry](https://nfdi4culture.de/fileadmin/user_upload/registry/badges/nfdi4culturebadge.svg)](https://nfdi4culture.de/id/E3648) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) -# Edirom Online +
+ +**[Show cases](https://github.com/Edirom/Edirom-Online#-Show-cases) • +[Get started](https://github.com/Edirom/Edirom-Online#-Get-started) • +[Dependencies](https://github.com/Edirom/Edirom-Online#-Dependencies) • +[Roadmap](https://github.com/Edirom/Edirom-Online#-Roadmap) • +[Contributing](https://github.com/Edirom/Edirom-Online#-Contributing) • +[Get in touch](https://github.com/Edirom/Edirom-Online#-Get-in-touch) • +[Code of Conduct](https://github.com/Edirom/Edirom-Online#-Code-of-Conduct) • +[License](https://github.com/Edirom/Edirom-Online#-License)** -Edirom Online is a web application written in XQuery and JavaScript, and designed for deployment in [eXist-db](https://exist-db.org/). It is based on the work of the [_Edirom_-Project](https://edirom.de/edirom-projekt/) that originally was funded by the German Research Foundation (DFG). This software brings paperbased historio-critical editions of music texts to the web. +
-The software is still under high development and has to be seen as beta software. +# Edirom-Online -## Cloning this repository +Edirom-Online is a software for the **presentation and analysis of critical musical editions** in a digital format, particularly in the fields of musicology and philology. Edirom-Online supports various data formats commonly used in digital humanities, such as [TEI] (Text Encoding Initiative) for textual data and [MEI] (Music Encoding Initiative) for musical data, that is visualized with [Verovio]. This allows for the integration of different data formats, starting in the early days with texts, images and music and adding audio and even film within a single edition. +The Edirom idea was born in 2004 at [Musikwissenschaftliches Seminar Detmold/Paderborn] and even after several years of Edirom development, the success of Edirom based on the same core concepts as in the beginning continues with numerous projects using and developing Edirom tools and creating digital musical editions with this software. Edirom tools were originally developed by the project [Entwicklung von Werkzeugen für digitale Formen wissenschaftlich-kritischer Musikeditionen] (2006–2012) funded by the DFG. The development of Edirom is now maintained as a community effort while being strongly supported and accompanied by [Virtueller Forschungsverbund Edirom] (ViFE), primarily based at [Paderborn University]. ViFE aims to provide tools for scholars working with digital texts and music, especially those involved in editing historical documents. -Since this repository uses submodules for e.g. fonts, it is necessary to clone the repository with the recursive addition. +## Show cases + +To get some practical insights, look at these projects and editions that already use Edirom-Online. + +**Clarinet quintet op.34 by Weber** + +The third version of Webers clarinet quintet op.34 was created 2022 by Virtueller Forschungsverbund Edirom (ViFE) honoring Prof. Dr. Joachim Veit on the occasion of his retirement. The edition includes digital facsimiles, music that is encoded in MEI and visualized with , annotations and texts. + * publication of [Webers clarinet quintet] + + + +**Freischütz Digital** + +The digital edition of Webers Freischütz was developed by the project "[Freischütz Digital] – Paradigmatische Umsetzung eines genuin digitalen Editionskonzepts" (BMBF, 2012–2015). Several demonstrators were developed and integrated into the Edirom-Online, e.g. 'Dynamic Score Rendering' and 'Genetic Text Stages'. + * publication of [Webers Freischütz] + * code of [Freischütz: Edirom-Online] + + + +**Bargheer: Fiedellieder plus** + +"Carl Louis Bargheer: Fiedellieder plus - Eine digitale Edition" was created 2013 as a students project at Musikwissenschaftliches Seminar Detmold/Paderborn with an early version of Edirom-Online. + * publication of [Bargheers Fiedellieder] + * code of [Bargheer: Edirom-Online] + * data of [Bargheer: Edition] + + + + +## Get started + +Edirom Online is a web application written in XQuery and JavaScript, and designed for deployment in [eXist-db]. +Please be aware, the software is still under high development and has to be seen as beta software. + +### Cloning this repository + +Since this repository uses submodules for e.g. fonts, it is necessary to clone the repository recursively. ```bash git clone --recursive @@ -20,39 +66,101 @@ If the submodules are not yet present after cloning, you can update them with: git submodule update --init --recursive ``` -## Dependencies - -Edirom Online depends heavily on the JavaScript framework [Ext JS](https://www.sencha.com/products/extjs) which is included in parts in our code base. We use Ext JS 4.2.1 in the GPL version. Edirom Online also includes the Raphaël javscript library (, MIT License) and the ACE editor (, BSD license). - -## Contributing - ### Building locally -For building Edirom Online you need *Sencha Cmd* installed on your system. You might want to refer to the [Sencha Cmd System Setup](https://docs.sencha.com/cmd/7.5.0/guides/intro_to_cmd.html#intro_to_cmd_-_system_setup) section for more details. +For building Edirom Online you need *Sencha Cmd* installed on your system. You might want to refer to the [Sencha Cmd System Setup] section for more details. -Alternatively we recommend to use a container image for building, e.g. [bwbohl/sencha-cmd](https://github.com/bwbohl/sencha-cmd/pkgs/container/sencha-cmd) +Alternatively, we recommend to use a Docker container image for building, e.g. [bwbohl/sencha-cmd] ```bash docker run --rm -it -v /ABSOLUTE/PATH/TO/YOUR/LOCAL/EDIROM-ONLINE/CLONE:/app --name ediBuild ghcr.io/bwbohl/sencha-cmd:latest ``` -When you have your system preapared with all Sencha Cmd prerequisites or you have your docker container running you have to execute a sencha build command through calling the build script included in this repository with one of the sencha build-type options (please refer to [sencha app build reference](https://docs.sencha.com/cmd/guides/advanced_cmd/cmd_reference.html#advanced_cmd-_-cmd_reference_-_sencha_app_build) for details), either in your native shell or in the container shell, e.g.: +When you have your system prepared with all Sencha Cmd prerequisites or you have your docker container running you are now set up to execute the sencha build command. Do this by calling the build script included in this repository with one of the sencha build-type options (please refer to [sencha app build reference] for details), either in your native shell or in the container shell, e.g.: ```bash ./build.sh testing ``` -### Testing locally +### Starting an Edirom instance locally + +* prepare **exist-db** + * also see [exist-db via Docker] + * `docker run -it -d -p 8080:8080 -p 8443:8443 --name exist stadlerpeter/existdb:6` (see stadlerpeter/existdb) + * open in browser: `http://localhost:8080` (Note: there were problems opening this in Safari) + * Login with "admin:[empty]" +* build and deploy **xar of Edirom** + * also see [building Edirom locally] above + * at `http://localhost:8080/exist/apps/dashboard/admin#` (signed-in) go to "Package Manager" then "Upload" and select the xar file which (supposed above build-method was used) was built at `/PATH_TO_LOCAL_EDIROM_REPO/build-xar/Edirom-Online-1.0.0-beta.5-[TIMESTAMP].xar` +* build **xar of sample data** for deploying at exist-db + * also see [building sample data] + * at `http://localhost:8080/exist/apps/dashboard/admin#` (signed-in) go to "Package Manager" then "Upload" and select the xar file which (supposed above build-method was used) was built at `/PATH_TO_LOCAL_EDIROM_EDITION_EXAMPLE_REPO/build/EditionExample-0.1.xar` +* in **eXist-db Package Manager** click on the "Edirom Online" entry - you will be directed to the running Edirom at `http://localhost:8080/exist/apps/Edirom-Online/index.html` + +## Dependencies + +Edirom Online depends heavily on the JavaScript framework [Ext JS] which is included in parts in our code base. We use Ext JS 4.2.1 in the GPL version. Edirom Online also includes the [Raphaël] javascript library (MIT License) and the [ACE] editor (BSD license). -It is essential to Test your modifications before committing or issuing a pull request. A recommended way is running a local eXist-db v5.3 container and deploying your local build of Edirom Online together with some test-data, e.g. the [Edirom Edition Example](https://github.com/Edirom/EditionExample). +## Roadmap -## Other deployment methods +Until today Edirom-Online and its features were developed as one application with strong dependencies on the JavaScript framework [Ext JS] (current version Ext JS 4.2.1) like mentioned above. Frontend and backend are currently living in this one application. Regarding to Edirom-Onlines release plans ExtJS is planned to be updated in the near future until ExtJS 7.0.0. +With the help and under the guidance of the project "[Edirom-Online Reloaded]" (funded by the DFG, 2024–2026) Edirom will exprerience some major updates and improvements to achieve sustainability of the software, e.g features and functionalites will be modularized as [edirom web components] and also a separation of frontend and backend and a crucial reduction of dependencies especially regarding frameworks is envisaged. In addition [ZenMEM] will continue to support and coordinate the sustainable development of the Edirom-Online software. +See the [Edirom-Online milestones] for more details. -Please see our documentation in the [wiki](https://github.com/Edirom/Edirom-Online/wiki). +## Contributing + +After all this information, you decided to conribute to Edirom-Online, that is awesome! We prepared a [CONTRIBUTING] file to help start your Edirom-Aventure now. + +## Get in touch + +Even if you are not ready (yet) to contribute to this wonderful project, maybe instead you just have a question or want to get to know the people involved in the project a little better, here are some ideas for you: +* there is an [Edirom mailinglist] with the option for selfsubscription +* the edirom community is meeting regularly every month at the first wednesday of a month, more information will be promoted via the mailinglist +* start a discussion at [GitHub Discussions] + +## Code of Conduct + +Please note that this project is released with a [Contributor Code of Conduct]. By participating in this project you agree to abide by its terms. ## License -Edirom Online is released to the public under the terms of the [GNU GPL v.3]() open source license. +Edirom Online is released to the public under the terms of the [GNU GPL v.3] open source license. + +[Musikwissenschaftliches Seminar Detmold/Paderborn]: https://www.muwi-detmold-paderborn.de/ +[TEI]: https://tei-c.org/ +[MEI]: https://music-encoding.org/ +[Virtueller Forschungsverbund Edirom]: https://github.com/Edirom +[Paderborn University]: https://www.uni-paderborn.de/en/ +[Entwicklung von Werkzeugen für digitale Formen wissenschaftlich-kritischer Musikeditionen]: https://edirom.de/edirom-projekt/ +[Webers clarinet quintet]: https://klarinettenquintett.weber-gesamtausgabe.de/ +[Freischütz digital]: https://freischuetz-digital.de/ +[Webers Freischütz]: https://edition.freischuetz-digital.de/ +[Freischütz: Edirom-Online]: https://github.com/Freischuetz-Digital/Edirom-Online +[Bargheers Fiedellieder]: https://bargheer.edirom.de/index.html +[Bargheer: Edirom-Online]: https://github.com/Edirom/Bargheer-EdiromOnline +[Bargheer: Edition]: https://github.com/Edirom/Bargheer-Edition +[eXist-db]: https://exist-db.org/ +[Verovio]: https://www.verovio.org/index.xhtml +[Ext JS]: https://www.sencha.com/products/extjs +[Raphaël]: http://raphaeljs.com +[ACE]: http://ace.ajax.org +[edirom web components]: https://github.com/Edirom/edirom-web-components-demonstrator +[Edirom-Online Reloaded]: https://www.uni-paderborn.de/projekt/1332 +[Edirom-Online milestones]: https://github.com/Edirom/Edirom-Online/milestones +[ZenMEM]: https://www.uni-paderborn.de/zenmem +[CONTRIBUTING]: CONTRIBUTING.md +[Sencha Cmd System Setup]: https://docs.sencha.com/cmd/7.5.0/guides/intro_to_cmd.html#intro_to_cmd_-_system_setup +[bwbohl/sencha-cmd]: https://github.com/bwbohl/sencha-cmd/pkgs/container/sencha-cmd +[sencha app build reference]: https://docs.sencha.com/cmd/guides/advanced_cmd/cmd_reference.html#advanced_cmd-_-cmd_reference_-_sencha_app_build +[exist-db via Docker]: https://exist-db.org/exist/apps/doc/docker +[stadlerpeter/existdb]: https://hub.docker.com/r/stadlerpeter/existdb +[building Edirom locally]: https://github.com/Edirom/Edirom-Online?tab=readme-ov-file#building-locally +[building sample data]: https://github.com/Edirom/EditionExample?tab=readme-ov-file#building +[Edirom mailinglist]: https://lists.uni-paderborn.de/mailman/listinfo/edirom-l +[GitHub Discussions]: https://github.com/Edirom/Edirom-Online/discussions +[Contributor Code of Conduct]: CODE_OF_CONDUCT.md +[GNU GPL v.3]: http://www.gnu.org/copyleft/gpl.html +