1. Table of contents

• 1. Table of contents
• 2. Updating dependencies
• 3. Contributing and reviewing PRs
  • 3.1. Prerequisites
  • 3.2. Making changes on your branch
  • 3.3. Continuous integration
  • 3.4. Pushing / committing
  • 3.5. Role as a PR reviewer
• 4. Syncing commits from upstream
  • 4.1. Pulling SVN revisions
  • 4.2. Merging SVN commits to Staging
• 5. Updating documentation
  • 5.1. Generating language files
  • 5.2. Update copyright dates
  • 5.3. Release notes & website updates
• 6. Releasing a new version

2. Updating dependencies

• PVS Studio: Linux .deb package, workflow, and license details.
• Coverity: Linux package, re-packaging steps, workflow, and license details.
• Track and update source dependencies:
  • mt32emu -> update the wrap and request and update in vcpkg.
  • fluidsynth -> update the wrap and request and update in vcpkg.
  • dr_libs in src/libs/decoders -> update dr_wav, dr_mp3, dr_flac (every couple months)
  • stb_vorbis in src/libs/decoders -> merge only new useful fixes individually, as our version has fixes and API changes needed for Staging.
  • residfp in src/libs/residfp -> merge only new fixes, as our copy has many c++ warning cleanups that haven't been fixed upstream yet.

3. Contributing and reviewing PRs

3.1. Prerequisites

• Learn about the project's goals
• Read the project's Coding Style Guide
• Read effective C++14/17 references [link]
• Create a GitHub account
• Fork the project on GitHub
• Make a branch for your change, named <alias-or-initials>/<feature>-<version> -> kc/add-ps1-audio-1
• Read good-commit-message guide

3.2. Making changes on your branch

• If you'd like to help improve Staging (and join the maintenance team), then your work will ultimately become a pull request (PR) in need of review before merging. Before diving into the code, please read The (written) unwritten rules about PRs which will maximize your use of time and maximize the chance of a successful PR.
• Separate types of changes into distinct commits: for example, normalizing function and variable names versus refactoring logic
• Each commit should compile
• Each commit should cover one cohesive change
• This approach ensures bugs and regressions can be isolated to a single commit using git-bisect
• Use ./scripts/format-commits.sh to format commits as you go (manually adjust if readability is notably harmed)

3.3. Continuous integration

• When pushing to GitHub, inspect the CI results on the 'Actions' page
• New warnings or new analyzed bugs will block merges
• Some warnings are acceptable (MAYBE_UNUSED under Clang and deprecated string security warnings under MSVC2022), in these cases update the allowed warnings under ./github/workflow/*.yml

3.4. Pushing / committing

• Push your branch and open a PR for review
• Address comments using fixup! or squash changes
• Request one, ideally two reviewers (depending on availability)

3.5. Role as a PR reviewer

Some good reading:

• The (written) unwritten rules about PRs
• 5 Tips That'll Help You Become a Better Code Reviewer
• PR Reviews Tips

4. Syncing commits from upstream

4.1. Pulling SVN revisions

1. Checkout the po/better-import-script branch

2. cd ./scripts/import-from-svn

3. ./import-from-svn.sh

    ...
    * [new tag]           svn/RELEASE_0_72                -> svn/RELEASE_0_72
    * [new tag]           svn/RELEASE_0_73                -> svn/RELEASE_0_73
    * [new tag]           svn/RELEASE_0_74                -> svn/RELEASE_0_74
    * [new tag]           svn/RELEASE_0_74_2              -> svn/RELEASE_0_74_2
    * [new tag]           v0.75.0                         -> v0.75.0
    * [new tag]           v0.75.0-pre                     -> v0.75.0-pre
    * [new tag]           v0.75.0-rc1                     -> v0.75.0-rc1
    * [new tag]           v0.75.1                         -> v0.75.1
    * [new tag]           v0.76.0                         -> v0.76.0
    * [new tag]           v0.76.0-alpha                   -> v0.76.0-alpha
    * [new tag]           v0.77.0-alpha                   -> v0.77.0-alpha
   Rebasing (22/74)
   
   Rewrite e1af839420cf0f607fc164139257117e0ec82ae3 (63/74) (1 seconds passed, remaining 0 predicted)    
   Ref 'refs/heads/svn/trunk' was rewritten
   
   Tip of svn/trunk in dosbox-git-svn-4459:
   
   1e7fd30c (HEAD -> svn/trunk, dosbox-staging/svn/trunk) Remove unused class template.
   
   Inspect new commits in dosbox-git-svn-4459 in detail.
   If the import looks good, invoke:
   
       $ git -C dosbox-git-svn-4459 push dosbox-staging svn/trunk:svn/trunk
   

Sequential sanity check

Before proceeding, confirm that the latest SVN commit number (4459 in the example above) is still sequential before the prior merged commits, without skips. An example without skips: [4456, 4457, 4458, 4459]. If there are no skips, then this is a "fast-import" scenario and you can skip to the procedure below.

If there are skips, ie: [4456, 4459], then one of three things happened:

1. A commit was made, but it was done outside of the DOSBox project portion of the repo. For example, maybe a PHP script was updated inside the "web" project portion. If you confirm this is case, then this is a "fast-import" scenario and you can skip to the procedure below.

2. If the skip can be attributed to a commit inside the project, for example due to an branch/tag/release (this can be assessed using svn log -v https://svn.code.sf.net/p/dosbox/code-0/dosbox | less or by browsing to https://sourceforge.net/p/dosbox/code-0/commit_browser)., New boundary commit IDs should be found after the new branch/tag/release, and those can be brought into the "fast-import" script.

3. If SVN's properties changed (TBD: add detail on how this is determined), then run the "full import" script instead.

Fast-import scenario

Context: the script creates a new mini-repo subdirectory containing an svn/trunk branch with new commits.

1. cd dosbox-git-svn-<revision>, Inspect the commit(s).
2. cd ..
3. Perform the indicated push command, as provided by the import script.

4.2. Merging SVN commits to Staging

(After the new commit has been pushed per steps above)

1. git fetch

2. git checkout svn/trunk

3. git reset --hard origin/svn/trunk

4. git checkout main

5. git checkout -b <your-initials>/merge-r<revision>, example used in the follow) git checkout -b kc/merge-4468

6. git merge svn/trunk

7. Update the commit comment to be exactly: "Merge 'svn/trunk' rREVISION"

   After resolving conflicts (possibly adding new commits), use gitk to confirm the svn/trunk branch exists in parallel to Staging's main branch:

   

8. git push -u origin kc/merge-4468

9. Address any CI issues with new commits, and reconfirm svn/trunk still appears like in the screenshot.

10. git checkout main

11. git reset --hard 6d49e2b492cb2978ca8c4220d703d7537d1c6465 <- where this is the last commit on kc/merge-4468

12. gitk (to confirm that everything's ok)

13. and if it's ok: git push origin main

5. Updating documentation

• README.md
• BUILD.md
• Translation files in contrib/translations
• PACKAGING.md [TBD]
• Read DOCUMENTATION.md for general information on updating the website and the user documentation.

5.1. Generating language files

See scripts in contrib/translations.

FIX ME: Currently the translation sources include an architecture hotkey #define "Cmd" (or "Ctrl") depending on the architecture. For 0.78, update the encode.sh and generate these on the CI platform, so the resulting release files contain the translation files with the right platform-specific define being used.

• encode.sh should be run when [condition? - TBD]
• update-en.sh should be run when [condition? - TBD]

5.2 Update copyright dates

Staging stamps copyrights on files spanning the dates of actual changes: starting with creation to the last modification date. We don't carte-blanche bump dates until the content has changes. See discussion: https://github.com/dosbox-staging/dosbox-staging/pull/1668#issuecomment-1126794872

In general, scripts/update-copyright-date.sh should be run before year-end to catch all files that were touched but author forgot to update the copyright line.

Before a release:

• update the dates on any metadata files and "--version" messages, which inform about copyright of whole package or binary
• run scripts/update-copyright-date.sh to update metadata and prepare for any releases in the incoming year

5.3. Release notes & website updates

1. Confirm in-source-repo documentation is up-to-date (README.md, BUILD.md, various other build-related documentation, etc.)
2. Cross-check dependency version changes (Meson, SDL, GCC, Clang, MT32, FluidSynth, etc.) against documentation (README.md, BUILD.md, PACKAGERS.md, Fedora build spec, etc.)
3. Make the changes for the new release in the main branch of the https://github.com/dosbox-staging/dosbox-staging repo (please familiarise yourself with how the website and the documentation are maintained and generated by reading DOCUMENTATION.md)
4. Copy old release notes file to create the new release notes file here
5. Rounds up changes:
   • Look through old PRs starting from prior release date through to the current date.
   • Insert commands to round up contributors, SVN commits, and numeric stats from the repo.
6. Populate new release notes; make sure to follow the structure of the last release notes for consistency. Always look for existing patterns in previous release notes before inventing new styles and ways of presenting information—earlier release notes are full of useful Markdown styling examples.
7. Update the front page of the website (website/overrides/home.html):
   • Update the latest release version.
   • Update the feature highlights section if necessary.
8. Verify the updated front page, the release notes, and the updated download pages locally, or at https://dosbox-staging.github.io/preview/dev/ (currently, updates need to be deployed manually as described here).

6. Releasing a new version

See the Release process page.