TP Process - Git CLI Commands

[rgleason]

Opensource Accounts

1. Github Account
2. CircleCI Account (if a TP collaborator on github/rgleason) this is not needed)
3. Cloudsmith Account (if the repository is already setup, this may not be required)

Process Overview

Github (code repository) ---> CircleCI (build and deploy) ---> Cloudsmith repository (metadata and tarball storage) ---> Github.com/OpenCPN/plugins/[master] using a script

Git Basics

You have remote origin and remote upstream properly configured.

git remote -v

You know and understand what branch you are on.

git branch OR git branch -va

If you are not on the right branch use

git checkout [branch name]

make sure local commit is the same as remote commit and no PR's have been merged. if they don't match use

git pull origin [branch]

The other good alternative to be sure the code you are working with is current, is to fork another user's repository and then clone or if you've already forked, use the github web interface to make a PR to your remote and merge it. Then you can clone your remote repository.

Then make changes to the code

git status   to see what needs to be added
git add  ..  multiple times to get everything needed for commit.

Push Commits to Github

How commits are pushed determines which Cloudsmith repository will be used for deployment. Process: Github --> CircleCI --> Cloudsmith Repositories (deployed files)

• [plugin-name]-prod <-- For production releases
• [plugin-name]-beta <-- Testing
• [plugin-name]-alpha <-- Quick check of builds

Push to Cloudsmith [plugin]-alpha repository via CircleCI

• for checking that all of the plugins OS build properly.
• tarballs and metadata will not be saved long
• from any branch other than "master" (master will land in Cloudsmith [plugin]-beta)
• "tagged" push is NOT needed

First make code changes and perhaps build locally and test. Does not need to have version number changed in CMakeLists.txt or just increment the "tweak" number.

git commit -am "[version optional] brief description"
git push --tags origin [branch]

Push to Cloudsmith [plugin]-beta repository via Github & CircleCI

• from "master" branch without a "tagged" push
• from any other branch with a "tagged" push

First make code changes and perhaps build locally and test. Does not need to have version number changed in CMakeLists.txt or just increment the "tweak" number.

Non-master branch

git commit -am "[version] brief description"
git tag v[version]    -needed for non "master" branches
git push --tags origin [branch]:[branch] OR  git push --tags origin [branch]  -needed for non-master branches

Master branch just use

git commit -am "[version] brief description"
git push  origin [master]

Push to Cloudsmith [plugin]-prod repository via Github & CircleCI

• Must be "master" branch
• Must be a "tagged" push

First make code changes and perhaps build locally and test. Change version number in CMakeLists.txt incrementing by one if not a big change, or increment tweak if not going to release yet.

git commit -am "[version] brief description"
git tag v[version]
git push --tags origin master:master     <--This is a tagged push

Work from [non-master] branch and Push direct

to Cloudsmith [plugin]-prod repository via Github & CircleCI

• from a "non-master" branch with a "tagged" push to "master" branch
• so that Cloudsmith deployment is to [plugin]-prod repository

git commit -am "[version] brief description"
git tag v[version]
git push --tags origin [non-master]:master   <--This is a tagged push

Circleci Builds

Getting all OS built can be challenging. General Rule: Commit one plugin at a time and let it complete. Sometimes a build fails and has to be

• "Rerun from fail" which tries to rerun all failed OS scripts.
• "Rerun using SSH" which just reruns that OS script alone. Another strategy when the Circleci cloud based machine seems bogged down is to
• Cancel duplicate runs that are not needed from the Circleci dashboard.
• Cancel runs that are older and a previous commit.
• Clean up the processing so what you want done has a faster chance of being done.
• Don't unnecessarily use Circleci credits, we are only allotted so many per month.

Push metadata up to opencpn/plugins

This process uses a script in the root of the plugins repository. When run it will download the files into the metadata directory under the root. Hence the need to be in the correct version, prod/beta/alpha, and have your own cloned branch for the push so you don't impact others.

First fork github.com/opencpn/plugins from your remote github account using the web browser. Then clone your remote down to your local computer.

Refer to the frontend workflow The goal is to

1. copy the plugin [version] metadata from Cloudsmith into your local plugins repository
2. commit the changes in the metadata folder.
3. push the commit up to your remote
4. make a PR back to github.com/opencpn/plugins

github.com/OpenCPN/plugins

master  - plugin releases 
Beta     - used for more stable plugin testing
alpha    - used for quick experimental plugin testing.

Checkout the appropriate branch of plugins and make sure it is current with upstream

git pull upstream [master]   <--substitute the branch you want to use.
git push origin [master]    <--substitute the branch you want to use.

Using a bash prompt from the plugin folder with the right branch checked out, at the root directory of plugins, copy the desired metadata into the local repository with the script:

bash ./download_xml_bash.sh [plugin-name] [version] opencpn [prod, beta or alpha]

For example

bash ./download_xml_bash weather-routing 1.9.100.0 opencpn prod <--Note hyphen instead of "_"

There are a couple of things to keep in mind:

• Use hyphen instead of "_".
• Don't use "_pi" with the plugin name
• If metadata is not found check your source on Cloudsmith then check your command details.

Then file browse to plugins/metadata and find your plugin and delete the old metadata version.

git add metadata
git commit -am "[plugin-name] [version]"
git push origin [master]

Then using your browser make a PR from your remote plugin repository to opencpn/plugins repos. Then bdbcat will review and merge your PR commit.

Handling Submodules (opencpn-libs)

Submodule OpenCPN/opencpn-libs For commands see the Instructions at the bottom.

TP Collaborators on github/rgleason

(if you don't know about this it is not you) TP Collaborators on github/rgleason should be able to:

1. Push a commit to their remote fork.
2. Make a PR to rgleason repositories and merge that PR.
3. Monitor and manage the rgleason plugin on github and circleci
4. Finally, also push to OpenCPN/plugins to update the plugin.

Members of Cloudsmith Opencpn Plugin Team can ceate and manage plugin repositories on Cloudsmith OpenCPN

General guidance:

1. Please push commits to your fork and then make a PR from your browser using github.com (don't make direct pushes)
2. Before merging a PR commit to the appropriate rgleason/[plugin] branch, check CircleCI to make sure it is not busy or hung up, unless you have turned off build and deployment in circleci/config.yml. Cancel and restart builds on CircleCI as appropriate.
3. If you have an opensource Cloudsmith account and are a member of the OpenCPN Plugin Team you can manage OpenCPN repositories.
4. If you don't have an opensource Cloudsmith account but are using CS repositories previously setup you should be able to use the script to Push metadata up to opencpn/plugins because these are open source repositories.

Local Build and Test

First make sure the submodule opencpn-libs is loaded $git submodule update --init opencpn-libs

Windows:

Use batch file "bld.bat". First use a VS 2022 Command Prompt to be able to review an output.txt file in the build directory.
Then use a Bash prompt to run the script which copies the metadata into the tarball so that it is compatible with "Import Plugin"

set "wxDIR=%WXWIN%"
set "wxWidgets_ROOT_DIR=%WXWIN%"
set "wxWidgets_LIB_DIR=%WXWIN%\lib\vc14x_dll" 
set "WXWIN=C:\Users\fcgle\source\wxWidgets-3.2.2"
REM  For Opencpn 5.8 and wxWidgets-3.2.2
cd build
cmake -T v143 -A Win32 -DOCPN_TARGET=MSVC ..
cmake --build . --target package --config relwithdebinfo >output.txt
bash ./cloudsmith-upload.sh

Linux & RPI

The trivial case for modern linux amd RPI plugins looks like this:

Make sure the submodule opencpn-libs is loaded

$git submodule update --init opencpn-libs

If wxWidgets is not found, set it locally in a bash script file. Adjust the path in WXWIN to match yours. How to Set environment variables in linux Note: Dave says the use if "set" for wxWidgets is unnecessary.

$mkdir build
$cd build
$cmake ..
$make
cp lib{whatever}_pi.so ~/.local/lib/opencpn

Start OCPN. The plugin will exist in the PIM list, as a pseudo-system plugin, as there is no metadata. But it can be enabled and tested like any other plugin. If the plugin requires private data, this will need to be copied manually.

Android

This will become available.

[bdbcat]

I think you mean: bash ./download_xml_bash weather-routing 1.9.100.0 opencpn prod

Note space instead of "_"

And where is the script "download_xml_bash.sh" ?

[jongough]

Its in the root of the plugins repository. When run it will download the files into the metadata directory under the root. Hence the need to be in the correct version, prod/beta/alpha, and have your own cloned branch for the push so you don't impact others.

[bdbcat]

OK, got it.