Skip to content

Improve README to match Appverse documentation standard #28

New issue
New issue
Open
Open
Improve README to match Appverse documentation standard#28
@a-pasquale

Description

@a-pasquale
a-pasquale
opened on Feb 24, 2026

Hi! As part of the OOD Appverse community, we're working to improve documentation consistency across Open OnDemand apps so that deployers at other sites can more easily evaluate, install, and adapt them.

We've put together a README template that covers the key sections deployers typically need when considering an app for their site.

Note: Open Composer is a Workflow Composer app (categorized under "Jobs"), not a typical Batch Connect interactive app. It generates and submits batch job scripts rather than launching interactive sessions. This makes it a unique and valuable addition to the OOD ecosystem.

After reviewing your current README, here's what we found:

Sections to add (not currently in your README):

  • Screenshots (the demo video is great, but a static screenshot would also help)
  • Features (a bullet-point list summarizing capabilities)
  • Requirements (Open OnDemand version, supported scheduler versions)
  • Configuration (summary of conf.yml and form.yml setup)
  • Troubleshooting
  • Testing (sites deployed table)
  • Known Limitations
  • Contributing
  • License section (in the README body, not just the LICENSE file)
  • Acknowledgments

Sections that could be expanded:

  • Overview -- could add a direct link to Open OnDemand and a brief summary of what the app does before linking to external documentation

Sections already present:

  • Overview -- clear one-line description of Open Composer's purpose
  • Installation -- links to detailed English and Japanese installation docs
  • Application settings -- links to English and Japanese configuration docs
  • User manual -- links to English and Japanese user manuals
  • Discussions -- link to GitHub Discussions
  • Supported job schedulers -- lists Slurm, PBS Pro, Grid Engine, Fujitsu_TCS
  • Demo -- embedded video demonstration
  • Reference -- citation with DOI link for the SC'25 publication
  • Presentation -- conference presentations and posters with links
  • Changelog -- detailed version history from v1.0.0 through v1.8.0 (latest release: v1.8.0)

Below we've provided two versions: a diff showing exactly what we're suggesting to add or change, and a clean copy-paste version you can drop in directly. Lines marked with <!-- TODO --> need your input -- we deliberately left those rather than guessing.

Diff view -- see exactly what's new and changed 
  ## Overview

  Open Composer is a web application to generate batch job scripts and submit batch jobs for HPC clusters on [Open OnDemand](https://openondemand.org/).

+ Open Composer is an [Open OnDemand](https://openondemand.org/) app in the "Jobs"
+ category. Unlike Batch Connect interactive apps, Open Composer provides a graphical
+ interface for creating, previewing, editing, and submitting batch job scripts. It
+ supports multiple job schedulers and can be configured for different HPC applications.
+
+ - **App type:** Workflow Composer (Jobs category)
+ - **Latest release:** [`v1.8.0`](https://github.com/RIKEN-RCCS/OpenComposer/releases/tag/v1.8.0)
+ - **License:** MIT
+
+ ## Screenshots
+
+ <!-- TODO: Add a screenshot of the Open Composer form or job submission interface -->

  - Installation (<a href="https://riken-rccs.github.io/OpenComposer/docs/install.html">English</a> | <a href="https://riken-rccs.github.io/OpenComposer/docs/install_ja.html">Japanese</a>)
  - Settings of application (<a href="https://riken-rccs.github.io/OpenComposer/docs/application.html">English</a> | <a href="https://riken-rccs.github.io/OpenComposer/docs/application_ja.html">Japanese</a>)
  - User manual (<a href="https://riken-rccs.github.io/OpenComposer/docs/manual.html">English</a> | <a href="https://riken-rccs.github.io/OpenComposer/docs/manual_ja.html">Japanese</a>)

- ## Disscussions
+ ## Discussions
  - https://github.com/RIKEN-RCCS/OpenComposer/discussions

  ## Supported job scheduler
  - Slurm
  - PBS Pro
  - Grid Engine
  - Fujitsu_TCS

+ ## Features
+
+ - Graphical web interface for generating and submitting batch job scripts
+ - Multi-scheduler support (Slurm, PBS Pro, Grid Engine, Fujitsu_TCS)
+ - Multi-cluster support
+ - Job history page with filtering, status tracking, and job cancellation
+ - Editable job script preview before submission
+ - Configurable application forms via `form.yml`
+ - Dynamic form widgets with conditional visibility and validation
+ - Support for preprocessing steps via submit sections
+ - Customizable per-application headers and labels
+ - Path selector widget for file and directory selection
+ - Bilingual documentation (English and Japanese)
+
+ ## Requirements
+
+ ### Open OnDemand
+
+ <!-- TODO: Specify the minimum OOD version this app has been tested with -->
+
+ ### Job Scheduler
+
+ One of the following:
+ - Slurm
+ - PBS Pro
+ - Grid Engine
+ - Fujitsu_TCS
+
+ ## App Installation
+
+ See the full installation guide:
+ - [English](https://riken-rccs.github.io/OpenComposer/docs/install.html)
+ - [Japanese](https://riken-rccs.github.io/OpenComposer/docs/install_ja.html)
+
+ ### Quick start
+
+ ```sh
+ cd /var/www/ood/apps/sys
+ git clone https://github.com/RIKEN-RCCS/OpenComposer.git
+ cd OpenComposer
+
+ # Pin to a release (recommended)
+ git checkout v1.8.0
+ ```
+
+ ## Configuration
+
+ Open Composer uses `conf.yml` for cluster and scheduler configuration and
+ per-application `form.yml` files to define job submission forms.
+
+ See the application settings documentation:
+ - [English](https://riken-rccs.github.io/OpenComposer/docs/application.html)
+ - [Japanese](https://riken-rccs.github.io/OpenComposer/docs/application_ja.html)

  ## Demo
  https://github.com/user-attachments/assets/0eee0b62-9364-465a-ae1e-7d412c1c9de9

+ ## Troubleshooting
+
+ <!-- TODO: Add troubleshooting tips you've encountered -->
+
+ ## Testing
+
+ <!-- TODO: Update with sites where this app has been deployed -->
+
+ | Site                     | OOD Version   | Scheduler     | Status     |
+ |--------------------------|---------------|---------------|------------|
+ | RIKEN RCCS               | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+ ## Known Limitations
+
+ <!-- TODO: Document any known limitations -->
+
+ ## Contributing
+
+ For discussions, see the [GitHub Discussions](https://github.com/RIKEN-RCCS/OpenComposer/discussions).
+
+ For bugs or feature requests,
+ [open an issue](https://github.com/RIKEN-RCCS/OpenComposer/issues).

  ## Reference
  If you use this software in your research or development work, please cite the following publication:

  > Masahiro Nakao and Keiji Yamamoto. 2025. ``Open Composer: A Web-Based Application for Generating and Managing Batch Jobs on HPC Clusters''. In Proceedings of the SC '25 Workshops of the International Conference for High Performance Computing, Networking, Storage and Analysis (SC Workshops '25). Association for Computing Machinery, New York, NY, USA, 697-704. https://doi.org/10.1145/3731599.3767428

  ## Presentation
  - [HUST: International Workshop on HPC User Support Tools](https://hust-workshop.github.io), St. Louis, USA, Nov. 2025 [[Paper](https://doi.org/10.1145/3731599.3767428)] [[Slide](https://www.mnakao.net/data/2025/HUST2025.pdf)]
  - [SupercomputingAsia 2025](https://sca25.sc-asia.org/), Singapore, Mar. 2025 [[Poster](https://mnakao.net/data/2025/sca.pdf)]
  - [The 197th HPC Research Symposium](https://www.ipsj.or.jp/kenkyukai/event/arc251hpc197.html), Fukuoka, Japan, Dec. 2024 [[Paper](https://mnakao.net/data/2024/HPC197.pdf)] [[Slide](https://mnakao.net/data/2024/HPC197-slide.pdf)] (Japanese)

+ ## References
+
+ - [Open OnDemand](https://openondemand.org/) -- the HPC portal framework
+ - [Open Composer documentation](https://riken-rccs.github.io/OpenComposer/)
+ - [Changelog](https://github.com/RIKEN-RCCS/OpenComposer/blob/main/CHANGELOG.md) -- release history
+
+ ## License
+
+ MIT (see LICENSE file)
+
+ ## Acknowledgments
+
+ <!-- TODO: Add funding or institutional support information -->
Clean README.md -- copy-paste ready 
## Overview

Open Composer is a web application to generate batch job scripts and submit batch jobs for HPC clusters on [Open OnDemand](https://openondemand.org/).

Open Composer is an [Open OnDemand](https://openondemand.org/) app in the "Jobs"
category. Unlike Batch Connect interactive apps, Open Composer provides a graphical
interface for creating, previewing, editing, and submitting batch job scripts. It
supports multiple job schedulers and can be configured for different HPC applications.

- **App type:** Workflow Composer (Jobs category)
- **Latest release:** [`v1.8.0`](https://github.com/RIKEN-RCCS/OpenComposer/releases/tag/v1.8.0)
- **License:** MIT

## Screenshots

<!-- TODO: Add a screenshot of the Open Composer form or job submission interface -->

- Installation (<a href="https://riken-rccs.github.io/OpenComposer/docs/install.html">English</a> | <a href="https://riken-rccs.github.io/OpenComposer/docs/install_ja.html">Japanese</a>)
- Settings of application (<a href="https://riken-rccs.github.io/OpenComposer/docs/application.html">English</a> | <a href="https://riken-rccs.github.io/OpenComposer/docs/application_ja.html">Japanese</a>)
- User manual (<a href="https://riken-rccs.github.io/OpenComposer/docs/manual.html">English</a> | <a href="https://riken-rccs.github.io/OpenComposer/docs/manual_ja.html">Japanese</a>)

## Discussions
- https://github.com/RIKEN-RCCS/OpenComposer/discussions

## Supported job scheduler
- Slurm
- PBS Pro
- Grid Engine
- Fujitsu_TCS

## Features

- Graphical web interface for generating and submitting batch job scripts
- Multi-scheduler support (Slurm, PBS Pro, Grid Engine, Fujitsu_TCS)
- Multi-cluster support
- Job history page with filtering, status tracking, and job cancellation
- Editable job script preview before submission
- Configurable application forms via `form.yml`
- Dynamic form widgets with conditional visibility and validation
- Support for preprocessing steps via submit sections
- Customizable per-application headers and labels
- Path selector widget for file and directory selection
- Bilingual documentation (English and Japanese)

## Requirements

### Open OnDemand

<!-- TODO: Specify the minimum OOD version this app has been tested with -->

### Job Scheduler

One of the following:
- Slurm
- PBS Pro
- Grid Engine
- Fujitsu_TCS

## App Installation

See the full installation guide:
- [English](https://riken-rccs.github.io/OpenComposer/docs/install.html)
- [Japanese](https://riken-rccs.github.io/OpenComposer/docs/install_ja.html)

### Quick start

```sh
cd /var/www/ood/apps/sys
git clone https://github.com/RIKEN-RCCS/OpenComposer.git
cd OpenComposer

# Pin to a release (recommended)
git checkout v1.8.0
```

## Configuration

Open Composer uses `conf.yml` for cluster and scheduler configuration and
per-application `form.yml` files to define job submission forms.

See the application settings documentation:
- [English](https://riken-rccs.github.io/OpenComposer/docs/application.html)
- [Japanese](https://riken-rccs.github.io/OpenComposer/docs/application_ja.html)

## Demo
https://github.com/user-attachments/assets/0eee0b62-9364-465a-ae1e-7d412c1c9de9

## Troubleshooting

<!-- TODO: Add troubleshooting tips you've encountered -->

## Testing

<!-- TODO: Update with sites where this app has been deployed -->

| Site                     | OOD Version   | Scheduler     | Status     |
|--------------------------|---------------|---------------|------------|
| RIKEN RCCS               | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |

## Known Limitations

<!-- TODO: Document any known limitations -->

## Contributing

For discussions, see the [GitHub Discussions](https://github.com/RIKEN-RCCS/OpenComposer/discussions).

For bugs or feature requests,
[open an issue](https://github.com/RIKEN-RCCS/OpenComposer/issues).

## Reference
If you use this software in your research or development work, please cite the following publication:

> Masahiro Nakao and Keiji Yamamoto. 2025. ``Open Composer: A Web-Based Application for Generating and Managing Batch Jobs on HPC Clusters''. In Proceedings of the SC '25 Workshops of the International Conference for High Performance Computing, Networking, Storage and Analysis (SC Workshops '25). Association for Computing Machinery, New York, NY, USA, 697-704. https://doi.org/10.1145/3731599.3767428

## Presentation
- [HUST: International Workshop on HPC User Support Tools](https://hust-workshop.github.io), St. Louis, USA, Nov. 2025 [[Paper](https://doi.org/10.1145/3731599.3767428)] [[Slide](https://www.mnakao.net/data/2025/HUST2025.pdf)]
- [SupercomputingAsia 2025](https://sca25.sc-asia.org/), Singapore, Mar. 2025 [[Poster](https://mnakao.net/data/2025/sca.pdf)]
- [The 197th HPC Research Symposium](https://www.ipsj.or.jp/kenkyukai/event/arc251hpc197.html), Fukuoka, Japan, Dec. 2024 [[Paper](https://mnakao.net/data/2024/HPC197.pdf)] [[Slide](https://mnakao.net/data/2024/HPC197-slide.pdf)] (Japanese)

## References

- [Open OnDemand](https://openondemand.org/) -- the HPC portal framework
- [Open Composer documentation](https://riken-rccs.github.io/OpenComposer/)
- [Changelog](https://github.com/RIKEN-RCCS/OpenComposer/blob/main/CHANGELOG.md) -- release history

## License

MIT (see LICENSE file)

## Acknowledgments

<!-- TODO: Add funding or institutional support information -->

Feel free to use as much or as little of this as you'd like -- we're happy to discuss any of these suggestions or adjust them to better fit your project.

This review is part of the OOD Appverse Affinity Group documentation effort. If you're interested in collaborating on documentation standards for OOD apps, consider joining the Appverse Affinity Group.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions