Please follow these principles for this repository:
- pull requests require 2+ approvals
- always work in forks
- do not merge your own changes
- follow release instructions
Here are a few recommendations for maintainers of this project:
- While this project is created as a fork from the original vscode-ros project, please do not merge
upstream/master
and push (unless planned). - Please do not alter commit history unless it is necessary and everyone working on the project is notified:
- do not use
git rebase
- do not use
git reset --hard
to revert to any commit earlier than currentHEAD
- try to avoid calling
git push --force
- do not use
- Please try not to directly push to
origin
, work with forks and merge changes through pull requests. - Only use tags to track releases.
This repository follows a simplified Forking Workflow (an adaptation from the Gitflow Workflow) to manage changes and branches.
- the Gitflow Workflow works with 5 types of branches:
master
: combined with tags to track all releasesdev
: for current codebase developmentrelease
: branches off fromdev
for release-related cleanup and udpatefeature
: branches off fromdev
for feature developmenthotfix
: branches off frommaster
for product code fix
- the Forking Workflow is based on the Gitflow Workflow yet most of the times without
feature
branches because:feature
branches are hosted in the developer's own fork, the centralized repository would not be hosting these branches
- this repository also does not use the
master
branch (themaster
branch in this repository acts as thedev
branch) because:- tags are adequate for tracking each release
hotfix
branches can branch off from the latest tag instead of themaster
branch (this is manageable when the project does not have too many releases)
Versioning of this extension follows the SemVer guidelines.
Given a version number
MAJOR.MINOR.PATCH
, increment the:
MAJOR
version when you make incompatible API changes,MINOR
version when you add functionality in a backwards-compatible manner, andPATCH
version when you make backwards-compatible bug fixes.Additional labels for pre-release and build metadata are available as extensions to the
MAJOR.MINOR.PATCH
format.
This project is not expected to have an insider's channel, so there are just some very simple guidelines to follow in practice:
- when any change is introduced into the
master
branch after the existing release (at this point, the version number in themaster
branch should be<current_version>
), update the version number in themaster
branch to<new_version>-dev
- after branching off to a release branch (
release/*
), the version number in the release branch stays the same as<new_version>-dev
- if any change comes into the
master
branch (instead of the release branch) at this point, the version number in themaster
branch should be updated to<even_newer_version>-dev
- if any change comes into the
- after the release branch has been reviewed and is ready to be released, update the version number to
<new_version>
and release- a newer version of the extension should be published as soon as the version number becomes
<new_version>
- a newer version of the extension should be published as soon as the version number becomes
Reasoning:
- VS Code extension marketplace hosts only the latest version; when there is no insider's channel, there is only 1 public version (the latest version)
- extensions can only be published with numeric SemVer versions, so no pre-release fields for final releases
- in order for packages installed from
.vsix
published from the vscode-ros.ci pipeline to receive updates to the final release on the VS Code extension marketplace, the version number shipped in the.vsix
package must be smaller. Therefore, the version numbers need to have the pre-release field (-dev
) - since there is no insider's channel, which means pre-release builds installed from
.vsix
will not receive auto-update to another pre-release build, there is no further versioning for the pre-release fields (no-alpha
,-beta
,-rc1
,-rc2
, etc.)
Please review the following before publishing a new release:
Metadata:
- update
README.md
- update
CHANGELOG.md
- update version number in
package.json
Release testing:
- Start, terminate, and monitor ROS core
- launch ROS core monitor with
ros.showMasterStatus
- start a new ROS core process in background with
ros.startCore
- check if ROS core monitor shows parameters and nodes correctly
- termintate the ROS core process with
ros.stopCore
- check if ROS core monitor shows "offline"
- launch ROS core monitor with
- Create a terminal with ROS environment sourced
- start a new ROS terminal with
ros.createTerminal
- check if ROS environment variables are properly configured
- start a new ROS terminal with
- Execute a ROS executable
- start a ROS core process (in another terminal or with
ros.startCore
) - execute
ros.rosrun
and choose an executable - check if the executable gets launched
- start a ROS core process (in another terminal or with
- Execute a ROS launch file
- execute
ros.roslaunch
and choose a launch file - check if the launch file gets launched
- execute
The release process can be automated by triggering a release pipeline from the vscode-ros.release pipeline; however, we will be simplifying the process to only release manually for now.
To authorize a release manually, schedule a release build with the proper release branch for the vscode-ros.release pipeline.
After the extension is released, the release branch should be:
- tagged with version number
- merged back into the
master
branch - deleted
Use tags to create snapshots of the codebase for each release. To create a new tag, follow these steps in a local ms-iot/vscode-ros
git repository:
-
Sync with remote
git pull
-
Create a new tag
git tag --list git log --oneline -n <log_number> git tag <tag_name> <commit_id> git push origin <tag_name>
-
Remove a tag
git tag --list git tag -d <tag_name> git push origin --delete <tag_name>