Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ OpenCite validates metadata at multiple stages:

## Metadata Rules

- Version values should match your planned GitHub release tag.
- Version values should match your planned GitHub release tag, except for an optional leading `v`.
- Grant IDs must use `<funder-code>::<grant-number>`.
- Publication date should be a real `YYYY-MM-DD` date.
- ORCID values are validated when provided.
Expand All @@ -157,7 +157,7 @@ OpenCite follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`
- `MINOR`: backward-compatible features
- `PATCH`: backward-compatible bug fixes

Use the exact version/tag string you intend to publish for your GitHub release.
Enter the exact GitHub tag separately when it differs from the metadata version.

## Release Workflow

Expand All @@ -172,7 +172,9 @@ When preparing a release:
4. Update `.zenodo.json` metadata when applicable.
5. Verify release metadata is consistent across GitHub, `CITATION.cff`, and `.zenodo.json`.

OpenCite automatically includes GitHub release and source-tree identifiers in `CITATION.cff` when a version and repository URL are present.
OpenCite includes the GitHub release URL in `CITATION.cff` when a version and repository URL are present. The release tag defaults to `v` plus the version, and can be edited to match the exact GitHub tag. If the tag and version differ (ignoring a leading `v`), the form displays a warning; the citation keeps the version and uses the tag for GitHub release links. A commit URL (`<repo-url>/commit/<commit-hash>`) is included when a valid release commit hash is available, with an `# Update on release` reminder. GitHub import fills in the exact tag and hash when the latest release tag matches the version.

Changing the version updates the default tag and clears the commit hash; a manually edited tag is preserved and checked against the new version. Changing the repository resets the tag to the version-based default and clears the hash. Changing the tag clears the hash.

## Grants Autofill

Expand Down
8 changes: 7 additions & 1 deletion src/App.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import { useEffect, useMemo, useRef, useState } from 'react';
import JSZip from 'jszip';
import { MetadataForm } from './components/MetadataForm.jsx';
import { normalizeMetadata } from './metadata/normalizeMetadata.js';
import { getDefaultReleaseTag } from './metadata/releaseTag.js';
import { updateMetadataField } from './metadata/updateMetadataField.js';
import { importGithubMetadata } from './services/githubImporter.js';
import { pickPreferredOrcidCandidate, searchOrcidCandidates } from './services/orcidSearch.js';
import { toCitationCff } from './services/citation.js';
Expand Down Expand Up @@ -34,6 +36,8 @@ const initialForm = {
version: '0.1.0',
publicationDate: '',
repositoryCode: '',
releaseTag: 'v0.1.0',
releaseCommit: '',
doi: '',
abstract: '',
references: '',
Expand Down Expand Up @@ -316,6 +320,8 @@ function metadataToForm(metadata) {
version: String(metadata.version ?? ''),
publicationDate: String(metadata.publicationDate ?? ''),
repositoryCode: String(metadata.repositoryCode ?? ''),
releaseTag: String(metadata.releaseTag ?? '') || getDefaultReleaseTag(metadata.version),
releaseCommit: String(metadata.releaseCommit ?? ''),
doi: String(metadata.doi ?? ''),
abstract: String(metadata.abstract ?? ''),
references: Array.isArray(metadata.references) ? metadata.references.join('\n') : '',
Expand Down Expand Up @@ -556,7 +562,7 @@ export default function App() {
function updateField(event) {
const { name, value } = event.target;
setTouchedFields((current) => ({ ...current, [name]: true }));
setForm((current) => ({ ...current, [name]: value }));
setForm((current) => updateMetadataField(current, name, value));
}

function appendGrantSuggestion(grantId) {
Expand Down
241 changes: 141 additions & 100 deletions src/components/MetadataForm.jsx
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { useState } from 'react';
import { releaseTagMatchesVersion } from '../metadata/releaseTag.js';

export function MetadataForm({
form,
Expand Down Expand Up @@ -218,113 +219,153 @@ export function MetadataForm({
<h3 id="section-publishing-title">Version, date, license, and identifiers</h3>
<p className="section-lede">Use release-aligned values so your exports match what users see on GitHub and Zenodo.</p>
</header>
<div className="section-grid">
<label className={shouldShowFieldError('typeOfWork') ? 'field-error' : ''}>
<span>Type of work*</span>
<select
className={shouldShowFieldError('typeOfWork') ? 'input-error' : ''}
name="typeOfWork"
value={form.typeOfWork}
onChange={updateField}
aria-invalid={Boolean(shouldShowFieldError('typeOfWork'))}
>
{typeOptions.map((option) => (
<option key={option.value} value={option.value}>
{option.label}
</option>
))}
</select>
{(hasTouchedField('typeOfWork') || importedMetadataAvailable) && errors.typeOfWork ? <small className="error-text">{errors.typeOfWork}</small> : null}
</label>
<div className="publishing-groups">
<div className="metadata-group" role="group" aria-labelledby="release-details-title">
<h4 id="release-details-title">Release details</h4>
<div className="metadata-fields">
<label className={shouldShowFieldError('typeOfWork') ? 'field-error' : ''}>
<span>Type of work*</span>
<select
className={shouldShowFieldError('typeOfWork') ? 'input-error' : ''}
name="typeOfWork"
value={form.typeOfWork}
onChange={updateField}
aria-invalid={Boolean(shouldShowFieldError('typeOfWork'))}
>
{typeOptions.map((option) => (
<option key={option.value} value={option.value}>
{option.label}
</option>
))}
</select>
{(hasTouchedField('typeOfWork') || importedMetadataAvailable) && errors.typeOfWork ? <small className="error-text">{errors.typeOfWork}</small> : null}
</label>

{form.typeOfWork === 'other' && (
<label>
<span>Specify type of work</span>
<input
name="customTypeOfWork"
value={form.customTypeOfWork}
onChange={updateField}
placeholder="e.g., protocol, poster, thesis"
/>
</label>
)}
{form.typeOfWork === 'other' && (
<label>
<span>Specify type of work</span>
<input
name="customTypeOfWork"
value={form.customTypeOfWork}
onChange={updateField}
placeholder="e.g., protocol, poster, thesis"
/>
</label>
)}

<label className={shouldShowFieldError('version') ? 'field-error' : ''}>
<span>Version*</span>
<input
className={shouldShowFieldError('version') ? 'input-error' : ''}
name="version"
value={form.version}
onChange={updateField}
placeholder="e.g. v1.2.3 or 1.2.3"
aria-invalid={Boolean(shouldShowFieldError('version'))}
/>
<small>Use Semantic Versioning (MAJOR.MINOR.PATCH), like <strong>1.2.3</strong> or <strong>v1.2.3</strong>. Use the exact value you plan to publish as your GitHub release tag.</small>
<small>
Need a refresher? See
{' '}
<a href="https://semver.org/" target="_blank" rel="noreferrer">semver.org</a>
.
</small>
{(hasTouchedField('version') || importedMetadataAvailable) && errors.version ? <small className="error-text">{errors.version}</small> : null}
</label>
<label className={shouldShowFieldError('version') ? 'field-error' : ''}>
<span>Version to cite*</span>
<input
className={shouldShowFieldError('version') ? 'input-error' : ''}
name="version"
value={form.version}
onChange={updateField}
placeholder="e.g. v1.2.3 or 1.2.3"
aria-invalid={Boolean(shouldShowFieldError('version'))}
/>
<small>
This is the version written to CITATION.cff (for example, 1.2.3). It usually matches your GitHub tag, except the tag may start with <strong>v</strong>.
{' '}
<a href="https://semver.org/" target="_blank" rel="noreferrer">Learn about Semantic Versioning</a>.
</small>
{(hasTouchedField('version') || importedMetadataAvailable) && errors.version ? <small className="error-text">{errors.version}</small> : null}
</label>

<label className={shouldShowFieldError('publicationDate') ? 'field-error' : ''}>
<span>Publication date</span>
<input
className={shouldShowFieldError('publicationDate') ? 'input-error' : ''}
name="publicationDate"
value={form.publicationDate}
onChange={updateField}
placeholder="YYYY-MM-DD"
aria-invalid={Boolean(shouldShowFieldError('publicationDate'))}
/>
{(hasTouchedField('publicationDate') || importedMetadataAvailable) && errors.publicationDate ? <small className="error-text">{errors.publicationDate}</small> : null}
</label>
<label className={shouldShowFieldError('publicationDate') ? 'field-error' : ''}>
<span>Publication date</span>
<input
className={shouldShowFieldError('publicationDate') ? 'input-error' : ''}
name="publicationDate"
value={form.publicationDate}
onChange={updateField}
placeholder="YYYY-MM-DD"
aria-invalid={Boolean(shouldShowFieldError('publicationDate'))}
/>
{(hasTouchedField('publicationDate') || importedMetadataAvailable) && errors.publicationDate ? <small className="error-text">{errors.publicationDate}</small> : null}
</label>

<label className={shouldShowFieldError('license') ? 'field-error' : ''}>
<span>License*</span>
<select
className={shouldShowFieldError('license') ? 'input-error' : ''}
name="license"
value={form.license}
onChange={updateField}
aria-invalid={Boolean(shouldShowFieldError('license'))}
>
<option value="">Select license (SPDX code)</option>
{licenseOptions.map((license) => (
<option key={license} value={license}>
{license}
</option>
))}
</select>
{(hasTouchedField('license') || importedMetadataAvailable) && errors.license ? <small className="error-text">{errors.license}</small> : null}
</label>
<label className={shouldShowFieldError('license') ? 'field-error' : ''}>
<span>License*</span>
<select
className={shouldShowFieldError('license') ? 'input-error' : ''}
name="license"
value={form.license}
onChange={updateField}
aria-invalid={Boolean(shouldShowFieldError('license'))}
>
<option value="">Select license (SPDX code)</option>
{licenseOptions.map((license) => (
<option key={license} value={license}>
{license}
</option>
))}
</select>
{(hasTouchedField('license') || importedMetadataAvailable) && errors.license ? <small className="error-text">{errors.license}</small> : null}
</label>
</div>
</div>

<label>
<span>Repository URL</span>
<input
name="repositoryCode"
value={form.repositoryCode}
onChange={updateField}
placeholder="https://github.com/user/repo"
/>
</label>
<div className="metadata-group" role="group" aria-labelledby="repository-release-title">
<h4 id="repository-release-title">Repository and release</h4>
<div className="metadata-fields">
<label>
<span>Repository URL</span>
<input
name="repositoryCode"
value={form.repositoryCode}
onChange={updateField}
placeholder="https://github.com/user/repo"
/>
</label>

<label>
<span>DOI (version-agnostic, from Zenodo)</span>
<input name="doi" value={form.doi} onChange={updateField} placeholder="10.0000/zenodo.example.doi" />
</label>
<label>
<span>GitHub release tag</span>
<input
name="releaseTag"
value={form.releaseTag ?? ''}
onChange={updateField}
placeholder="e.g. v1.2.3"
/>
<small>This is the exact Git tag on GitHub (for example, v1.2.3). It creates the release link in CITATION.cff; leave the suggested tag unless your GitHub tag is different.</small>
{form.releaseTag && form.version && !releaseTagMatchesVersion(form.version, form.releaseTag) && (
<small className="release-tag-warning" role="status">
The GitHub tag "{form.releaseTag}" does not match the cited version "{form.version}". The citation keeps the version above and links to this tag.
</small>
)}
</label>

<label>
<span>Keywords</span>
<input
name="keywords"
value={form.keywords}
onChange={updateField}
placeholder="open science, metadata, citation"
/>
</label>
<label>
<span>Release commit hash</span>
<input
name="releaseCommit"
value={form.releaseCommit}
onChange={updateField}
placeholder="Full commit hash tagged with this version"
/>
<small>Used in the CITATION.cff release commit link. Filled in automatically when import finds a matching release.</small>
</label>
</div>
</div>

<div className="metadata-group" role="group" aria-labelledby="identifiers-title">
<h4 id="identifiers-title">Identifiers and keywords</h4>
<div className="metadata-fields">
<label>
<span>DOI (version-agnostic, from Zenodo)</span>
<input name="doi" value={form.doi} onChange={updateField} placeholder="10.0000/zenodo.example.doi" />
</label>

<label>
<span>Keywords</span>
<input
name="keywords"
value={form.keywords}
onChange={updateField}
placeholder="open science, metadata, citation"
/>
</label>
</div>
</div>
</div>
</section>

Expand Down
4 changes: 4 additions & 0 deletions src/core/metadataModel.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@
* @property {string} version
* @property {string} publicationDate - ISO 8601 date string (YYYY-MM-DD)
* @property {string} repositoryCode - URL to code repository
* @property {string} releaseTag - actual GitHub release tag, when different from the version
* @property {string} releaseCommit - commit hash tagged with the release version
* @property {string} doi
* @property {string} abstract
* @property {string[]} references
Expand All @@ -39,6 +41,8 @@ export const emptyMetadata = {
version: '',
publicationDate: '',
repositoryCode: '',
releaseTag: '',
releaseCommit: '',
doi: '',
abstract: '',
references: [],
Expand Down
2 changes: 2 additions & 0 deletions src/metadata/normalizeMetadata.js
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ export function normalizeMetadata(form) {
version: form.version ?? '',
publicationDate: form.publicationDate ?? '',
repositoryCode: form.repositoryCode ?? '',
releaseTag: form.releaseTag ?? '',
releaseCommit: form.releaseCommit ?? '',
doi: form.doi ?? '',
abstract: form.abstract ?? '',
references,
Expand Down
14 changes: 14 additions & 0 deletions src/metadata/releaseTag.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
function normalizeReleaseIdentifier(value) {
return String(value ?? '').trim().replace(/^v/i, '');
}

export function getDefaultReleaseTag(version) {
const normalizedVersion = normalizeReleaseIdentifier(version);
return normalizedVersion ? `v${normalizedVersion}` : '';
}

export function releaseTagMatchesVersion(version, releaseTag) {
const normalizedVersion = normalizeReleaseIdentifier(version);
const normalizedTag = normalizeReleaseIdentifier(releaseTag);
return Boolean(normalizedVersion && normalizedTag && normalizedVersion === normalizedTag);
}
21 changes: 21 additions & 0 deletions src/metadata/updateMetadataField.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { getDefaultReleaseTag, releaseTagMatchesVersion } from './releaseTag.js';

export function updateMetadataField(form, name, value) {
if (form[name] === value) {
return form;
}

if (name === 'version') {
const releaseTag = !form.releaseTag || releaseTagMatchesVersion(form.version, form.releaseTag)
? getDefaultReleaseTag(value)
: form.releaseTag;
return { ...form, version: value, releaseTag, releaseCommit: '' };
}
if (name === 'repositoryCode') {
return { ...form, repositoryCode: value, releaseTag: getDefaultReleaseTag(form.version), releaseCommit: '' };
}
if (name === 'releaseTag') {
return { ...form, releaseTag: value, releaseCommit: '' };
}
return { ...form, [name]: value };
}
Loading
Loading