Appendix H — Contributing

QA catalogue is developed in a git repository at https://github.com/pkiraly/qa-catalogue. Bug reports and feature requests are managed in the corresponding issue tracker.

Contribution is welcome at:

H.1 Documentation

The documentation is build with quarto. It is published at https://pkiraly.github.io/qa-catalogue/ with every change on the main branch and on the docs branch.

H.2 Source code

We try to follow this git workflow:

H.2.1 1st scenario: preparing the first pull request

clone QA catalogue at https://github.com/pkiraly/qa-catalogue.git then

git clone https://github.com/YOUR_NAME/qa-catalogue.git qa-catalogue
cd qa-catalogue

create a new branch locally for the pull request (the name should reflect the ticket ID and title)

git checkout -b 123-COOL-FEATURE

working on the branch … then commit changes

git commit -am "issue #123: explanation of changes"

upload the new branch to https://github.com/YOUR_NAME/qa-catalogue

git push -u origin 123-COOL-FEATURE

… then create pull request at github.com/YOUR_NAME/qa-catalogue

H.2.2 2nd scenario: preparing another pull request some month later

register the main QA catalogue repo

git remote add upstream https://github.com/pkiraly/qa-catalogue.git

git checkout main

update local develop branch from https://github.com/pkiraly/qa-catalogue

git fetch upstream main
git rebase upstream/main

update remote develop branch at https://github.com/YOUR_NAME/qa-catalogue

git push

create a new branch locally for the pull request

git checkout -b 123-COOL-FEATURE

work on the branch and commit changes

git commit -am "#123 explanation of changes"

upload the new branch to https://github.com/YOUR_NAME/qa-catalogue

git push -u origin 123-COOL-FEATURE

… then create pull request at github.com/YOUR_NAME/qa-catalogue

H.2.3 3rd scenario: synchronize your branch with main branch

git checkout main

update local develop branch from https://github.com/pkiraly/qa-catalogue

git fetch upstream main
git rebase upstream/main

update remote develop branch at https://github.com/YOUR_NAME/qa-catalogue

git push

change to the already existing feature branch

git checkout 123-COOL-FEATURE

merge changes of develop to the feature branch

git merge main

check if there are conflicts, if there are follow the next command, otherwise skip to next block 1. fix the relevant files (including testing) 2. commit changes

git add <fixed files>
git commit

update remote feature branch at https://github.com/YOUR_NAME/qa-catalogue

git push

H.3 Entry points

The entry points of the application are the classes in the de.gwdg.metadataqa.marc.cli package (https://github.com/pkiraly/metadata-qa-marc/blob/main/src/main/java/de/gwdg/metadataqa/marc/cli/). These classes can be called directly from the command line.

The main idea is that there is a record iterator (RecordIterator), which iterates all over the files and records, and calls methods of the current class. During the iteration there are different events, and classes (usually extending the QACli class) as subscribers react to these events.

The events themselves are defined in the BibliographicInputProcessor interface, and the command line classes implement it. Here are the events:

  • beforeIteration(): calls it before the start of the iteration. Good for preparation steps, such as initializing things
  • fileOpened(Path path): a file is opened
  • processRecord(Record marc4jRecord, int recordNumber): a record is read. Here the record is in a low levele, semanticness-less “Record” class (mart of the external marc4j library), which contains the basic structure. You do not have to add any code here
  • processRecord(BibliographicRecord bibliographicRecord, int recordNumber): a record is read. Here the record is a BibliographicRecord class, which is our main class. You have to implement this method.
  • fileProcessed(): we get to the end of a file, no more record in the file
  • afterIteration(int numberOfprocessedRecords): the iteration is finished, no more files to process. You can print out all collected information, close open resources (if any) etc.

Please check classes in the de.gwdg.metadataqa.marc.cli package, such as the Completeness to study concrete examples.