Contributing

Contributing to the OWLNext project

Here are some ways you can contribute:

• Participate in the forums.
• Help us improve the information on this wiki.
• Submit feature requests, bug reports and patches to the trackers.

If you want to participate as an OWLNext developer or administrator with elevated access rights to the project site, then contact the current administrators by posting in the forum, at the bottom of this page or by email.

• Contributing to the OWLNext project
  • Guidelines for contributors
  • Administering the OWLNext project site
    • Tools
      • SSH
      • SFTP
      • RSync
    • Updating the online documentation
    • Code repository backup
    • References
  • Preparing and releasing a new version
    • OWLMaker release script

---

Guidelines for contributors

Contributors should follow these guidelines:

• Submitting bugs and feature requests; our guidelines for the tracker fields and contents.
• Coding Standards; our standards for patches and revisions to the OWLNext source code.
• Doxygen documentation guidelines; how to document the OWLNext API.

Here are some advice and prerequisites to get started:

• Get to know the code repository layout and the Subversion (SVN) version control system. The TortoiseSVN client for Windows is highly recommended and has good documentation.
• Make sure you thoroughly read the guidelines above. Look at the code log to get a feel for our style.
• Learn to use the issue trackers (Bugs and Feature Requests).
• Read and contribute to our Roadmap.
• Read and contribute to the documentation in our wiki.

---

Administering the OWLNext project site

The following sections contain some notes on project site management. The command line examples assume that your user name is "admin". Replace "admin" with your real user name. To get administrator privileges, contact the current administrators or SourceForge.

Tools

Various free command line tools are useful for working with the project site. The following examples are based on a Linux setup. If you work on Windows, you can e.g. use a virtual machine with Linux to use these tools. Another option is to use a GNU-style shell, such as Cygwin, or the Bash shell in Windows 10.

SSH

The SourceForge shell server lets you work on the project site for a limited amount of time (4 hours). The following command connects to SourceForge SSH shell server:

$ ssh -t admin,owlnext@shell.sourceforge.net create

SFTP

The following command is fine for doing single file (e.g. large zipped archive) transfer to and from the project web space:

$ sftp admin,owlnext@web.sourceforge.net

RSync

RSync works with SSH internally to provide secure, powerful and simple file transfer and synchronisation of file systems across the public network. For example, to copy the project website:

$ rsync -e "ssh -l admin" admin,owlnext@web.sourceforge.net:/home/project-web/owlnext/htdocs .

Updating the online documentation

RSync is well suited for updating the Online OWLNext Documentation. Assuming that you have the updated documentation files in the local folder "documentation/html", this command updates the online documentation:

$ rsync -avsz --delete -e "ssh -l admin" documentation/html admin,owlnext@web.sourceforge.net:/home/project-web/owlnext/htdocs/help/.

Code repository backup

Create and log into an SSH shell. Change the current directory to the code repository, and issue the "svnadmin dump" command. For example:

$ cd /home/svn/p/owlnext/code
$ svnadmin dump . > backup.dump

Then copy the dump file to your preferred backup destination. For example, use RSync from a local console:

$ rsync -e "ssh -l admin" admin,owlnext@shell.sourceforge.net:/home/svn/p/owlnext/code/backup.dump .

References

• https://www.software.ac.uk/guide/how-create-and-manage-sourceforge-projects

---

Preparing and releasing a new version

This section describes the administrative steps you need to perform to prepare and release a new version of OWLNext.

1. Unless the new version is a minor ABI-compatible update, create a new release branch in the code repository (i.e. create a copy in "branches/."), and set the OWL_PRERELEASE flag in "source/owlcore/version.h" to 1.
2. Update the version number in "source/owlcore/version.h" on the release branch.
3. If applicable, update OWLMaker to recognise the new version and the supported compilers.
4. Create new version milestones in the Bugs and Feature Requests tracker tools.
5. Create and/or target tickets for the version milestones.
6. Review the resolutions to the tickets.
7. Release:
   1. Do a full build test of all libraries and configurations, ideally with all supported compilers. Make sure OWL_BUILD_DIRTY == 0 in "include/owl/version.h", i.e. that you have no uncommitted changes in the source code. Make sure you test that the documentation builds without errors as well. Ideally, also run test cases ("examples/classes", in particular) to make sure changed parts work as intended and that there are no regressions.
   2. Unless the release is an unfinished developer preview (also known as an "alpha" or "beta" pre-release), set the OWL_PRERELEASE flag in "source/owlcore/version.h" to 0.
   3. Tag the state of the release branch in the code repository (i.e. create a copy in "tags"). See existing tags for the naming convention.
   4. Close the relevant tickets and milestones.
   5. Rebuild the documentation and upload an updated help file (CHM) to "Files/documentation". Before you build the documentation, make sure that build setup has been done, so that "include/owl/version.h" exists, and check that OWL_BUILD_DIRTY == 0 (no uncommitted changes). Unless the release is for an older version, update the online documentation as well (see section "Updating the online documentation" earlier on this page).
   6. Upload a snapshot of the updated version of the source code to "Files/source". See existing archives for the correct directory structure.
   7. If OWLMaker has changed, upload the updated version to "Files/tools". See the existing archive for the correct contents and directory structure. Ideally, you should digitally sign the executables in the archive (otherwise virus checkers, browsers and operating systems may deem them unsafe). This requires that you have access to a trusted code signing certificate, or that a trusted third-party entity (e.g. a trusted project member) can sign the executables for you. Also make sure that the archive passes virus checking (e.g. at VirusTotal).
   8. Update the version numbers in "Files/files-readme.md" (OWLMaker parses this file to check for updates).
   9. Document the release in the wiki page "OWLNext Releases". If relevant, update wiki pages "Installing OWLNext", "Supported Compilers", "Upgrading from OWL" (section "Changes in OWLNext"), "FAQ", as well as any other wiki page affected by the changes. Finally, update the wiki main page, section "Latest releases".
   10. Create a News post announcing the release.

OWLMaker release script

The following PowerShell script can be used to automate the release of a new version of OWLMaker.

The script should be located in a folder that contains a subfolder "OWLMaker Package Contents", which in turn contains the current contents of the OWLMaker package (e.g. "OWLMaker-6681.zip"). The script copies the 32-bit and 64-bit executables from the OWLMaker working directory to the corresponding folders within "OWLMaker Package Contents". You must update the script with the correct location of the OWLMaker working directory on your system.

To set the credentials for the script to access our Files download section, you can define environment variables SOURCEFORGE_USERNAME and SOURCEFORGE_PASSWORD for your user profile in Windows. Otherwise, the script will ask for credentials interactively. To perform file transfer operations, the script uses the Posh-SSH module, so it has to be installed on your system for the script to work.

The script starts by displaying the version of OWLMaker found in your working directory, then downloads and updates the catalog file ("files-readme.md") with the correct OWLMaker version number and package name.

After the executables have been copied from the working directory to "OWLMaker Package Contents", the script starts kSign, a code signing tool from K Software. You should update this part of the script for your code signing solution. If you do not have a code signing certificate, and unsigned executables are acceptable, then you can remove or disable this part of the script.

Finally, the script creates a new OWLMaker package and places it alongside the catalog file in the "Downloads" folder on your system. From there it then uploads the package and catalog to our Files download section. Note that the package is uploaded to the "tools" subfolder, while the catalog is uploaded to the root.

Note: Perform a thorough virus scan of the package, e.g. using the VirusTotal online service.

Clear-Host
$nl = "`r`n"
Write-Host -Separator $nl (
    "",
    "OWLMaker Release Script",
    "See OWLNext for license information (https://sourceforge.net/projects/owlnext).",
    "Copyright (c) 2023 Vidar Hasfjord",
    ""   
)

function Failure {
    param (
        [Parameter(Mandatory=$false)]
        [string]$ErrorMessage
    )
    if ($ErrorMessage) {
        Write-Host $ErrorMessage 
    }
    Write-Host
    Read-Host -Prompt "Press Enter to close"
    if ($Global:credential) { Remove-Variable credential -Scope Global }
    exit 1
}

# Define paths and check if they exist.

$owlMaker = "..\..\OWLMaker"
if (!(Test-Path $owlMaker)) { Failure "`"$owlMaker`" not found." }

$versionHeader = "$owlMaker\version.h"
if (!(Test-Path $versionHeader)) { Failure "`"$versionHeader`" not found." }

$applicationHeader = "$owlMaker\Application.h"
if (!(Test-Path $versionHeader)) { Failure "`"$applicationHeader`" not found." }

$owlMaker64Bit = "$owlMaker\build\x64\Release\OWLMaker\OWLMaker.exe"
if (!(Test-Path $owlMaker64Bit)) { Failure "`"$owlMaker64Bit`" not found." }

$owlMaker32Bit = "$owlMaker\build\Win32\Release\OWLMaker\OWLMaker.exe"
if (!(Test-Path $owlMaker32Bit)) { Failure "`"$owlMaker32Bit`" not found." }

# Check LOCAL_TESTING flag in "Application.h".

$localTestingFlagLine = Get-Content $applicationHeader| Select-String -Pattern 'LOCAL_TESTING (\d)'
$localTesting = $localTestingFlagLine.Matches.Groups[1].Value
if ($localTesting -ne "0") { Failure "LOCAL_TESTING is set in 'Application.h'. Did you forget to clear it?" }

# Get version number and prerelease flag from "version.h".

$versionLine = Get-Content $versionHeader | Select-String -Pattern 'OWLMAKER_VERSION\(v\) v\((\d+),(\d+),(\d+),(\d+)\)'
$year, $month, $day, $revision = $versionLine.Matches.Groups[1..4].Value
$owlMakerVersion = "$year.$month.$day.$revision"
$prereleaseFlagLine = Get-Content $versionHeader | Select-String -Pattern 'OWLMAKER_PRERELEASE (\d)'
$owlMakerPrerelease = $prereleaseFlagLine.Matches.Groups[1].Value

# Display version numbers.

Write-Host -Separator $nl (
    "Current version of OWLMaker detected:",
    "",
    "   OWLMAKER_VERSION = $owlMakerVersion",
    "   OWLMAKER_PRERELEASE = $owlMakerPrerelease",
    ""
)
if ($owlMakerPrerelease -ne "0") {
    Write-Host "Warning: OWLMAKER_PRERELEASE is set. Did you forget to clear it?$nl"
}

# Download the catalog file and show the current OWLMaker entry in the catalog.

$catalogFileName = "files-readme.md"
$catalog = "$env:HOMEPATH\Downloads\$catalogFileName"
$project = "owlnext"
$frsHost = "frs.sourceforge.net"
$frsPath = "/home/frs/p/$project"
$frsCatalogPath = "$frsPath/$catalogFileName"
$credential = if (!$env:SOURCEFORGE_USERNAME -or !$env:SOURCEFORGE_PASSWORD)
    {Get-Credential -UserName $env:SOURCEFORGE_USERNAME -Message "SourceForge credentials"} else
    {New-Object System.Management.Automation.PSCredential(
        $env:SOURCEFORGE_USERNAME, 
        (ConvertTo-SecureString $env:SOURCEFORGE_PASSWORD -AsPlainText -Force))}
if (!$? -or !$credential) { Failure "Failed to create PSCredential object." }
Write-Host "Starting catalog download..."
Get-SCPItem -Credential $credential -ComputerName $frsHost `
    -Path $frsCatalogPath -PathType File `
    -Destination $(Split-Path -Path $catalog -Parent)
if (!$?) { Failure "Failed to download catalog." }
Write-Host -Separator $nl (
    "Downloaded the catalog file `"$frsHost`:$frsCatalogPath`".",
    "",
    "Current catalog entry:",
    "",
    (Select-String -Pattern "- OWLMaker" -Path $catalog).Line,
    "",
    "The next step is catalog update (if necessary), file copy and code signing. The",
    "OWLMaker executable files will be copied to 'OWLMaker Package Contents', where",
    "they will be digitally signed.",
    ""
)
Read-Host -Prompt "Press Enter to continue"

# Update the catalog, if necessary.

$tmpCatalog = New-TemporaryFile
$packageFileName = "OWLMaker-$revision.zip"
Get-Content $catalog | ForEach-Object {
    $line = if ($_ -match "- OWLMaker")
        {" - OWLMaker ${owlMakerVersion}: tools/$packageFileName"} else
        {$_}
    $line | Out-File $tmpCatalog -Append ascii
}
if (Compare-Object (Get-Content $catalog) (Get-Content $tmpCatalog)) {
    Move-Item -Force -Path $tmpCatalog -Destination $catalog
    if (!$?) { Failure "Failed to update the downloaded catalog file." }
    Write-Host -Separator $nl (
        "Updated the downloaded catalog file:",
        "",
        (Select-String -Pattern "- OWLMaker" -Path $catalog).Line,
        ""
    )
    $isCatalogUpdated = $true
} else {
    Remove-Item -Force -Path $tmpCatalog -ErrorAction SilentlyContinue
    $isCatalogUpdated = $false
}
Remove-Variable tmpCatalog

# Copy files and initiate code signing.

$packageContents = "OWLMaker Package Contents"
Copy-Item -Force -Path $owlMaker64Bit -Destination "$packageContents\"
if (!$?) { Failure "Failed to copy `"$owlMaker64Bit`"." }
Write-Host "Copied `"$owlMaker64Bit`"."

Copy-Item -Force -Path $owlMaker32Bit -Destination "$packageContents\32-bit\"
if (!$?) { Failure "Failed to copy `"$owlMaker32Bit`"." }
Write-Host "Copied `"$owlMaker32Bit`"."

Start-Process "OWLMaker Package Signing.ksign"
if (!$?) { Failure "Failed to start kSign." }
Write-Host -Separator $nl (
    "Started kSign.",
    "",
    "Files have been copied and code signing initiated. Next step is package creation.",
    ""
)
Read-Host -Prompt "Press Enter to continue"

# Perform the package creation in Downloads.

$package = "$env:HOMEPATH\Downloads\$packageFileName"
Compress-Archive -Force -Path "$packageContents\*" -Destination $package
if (!$?) { Failure "Failed to create package." }
Write-Host -Separator $nl (
    "Created package `"$package`".",
    "",
    "Next step is to upload the package and the catalog (if updated).",
    ""
)
Read-Host -Prompt "Press Enter to continue"

# Upload the package and the catalog (if updated).

$packageDestination = "$frsPath/tools"
Write-Host "Starting package upload to `"$frsHost`:$packageDestination/$packageFileName`"..."
Set-SCPItem -Credential $credential -ComputerName $frsHost `
    -Path $package `
    -Destination $packageDestination
if (!$?) { Failure "Failed to upload the package." }
Write-Host "Completed package upload."

if ($isCatalogUpdated) {
    Write-Host "${nl}Starting catalog upload to `"$frsHost`:$frsPath/$catalogFileName`"..."
    Set-SCPItem -Credential $credential -ComputerName $frsHost `
        -Path $catalog `
        -Destination $frsPath
    if (!$?) { Failure "Failed to upload the catalog." }
    Write-Host "Completed catalog upload."
}
Remove-Variable credential

# We're done!

Write-Host -Separator $nl (
    "",
    "Done. Remember to update the `"Latest Releases`" section on the wiki home page,",
    "and set the new package as the default download for all operating systems.",
    "",
    "Also, you should upload the package to VirusTotal for a comprehensive scan.",
    "",
    "Congratulations on the release!",
    ""
)
$shouldDelete = (Read-Host -Prompt "Do you want to delete the local files? [y]es/[N]o").ToUpper().StartsWith("Y")
if ($shouldDelete) {
    Remove-Item -Force -Path $package -ErrorAction SilentlyContinue
    Write-Host "Deleted the package file `"$package`"."
    Remove-Variable package

    Remove-Item -Force -Path $catalog -ErrorAction SilentlyContinue
    Write-Host "Deleted the catalog file `"$catalog`"."
    Remove-Variable catalog

    Write-Host
    Read-Host -Prompt "Press Enter to close"
}
exit 0