Development Workflow

Theses details are for contributors not general VimDevIcon plugin users 😉

---

Table of Contents:

0. Prerequisites
1. KISS Workflow*
2. Branch Conventions
3. Versions
4. Automated Testing
5. Issues
6. New Release Workflow
7. New Release Vimscripts Upload
8. Code Standards

---

Prerequisites

• Git
• Python 2 and/or Python 3
• Vim-tools (specifically html2vimdoc)
• Follow install and setup instructions: https://github.com/xolox/vim-tools#dependencies
• Apply temporary fix: https://github.com/xolox/vim-tools/issues/10#issuecomment-262415272
• Vint
• pip install vim-vint

KISS Workflow*

This describes the overall workflow and release methodology for the VimDevIcons project.

Goals

• Keep contributor(s) barrier to entry as low as possible
• "Release early, release often"
• KISS (Keep it simple, stupid)

Overview

• master is basically the stable dev or nightly branch
• Pull Requests are simply merged in (not rebased)
• There are no squashing requirements at the moment
• Each release will have a tag and a branch
  • Tags will follow format of: vMAJOR.MINOR.PATCH
  • Branches will follow format of: MAJOR.MINOR.PATCH
• We are no longer creating tags/releases (more info)

Branch Conventions

Only time-critical bug fixes or possibly trivial doc changes go directly into the master branch.

As of 10th March 2018, VimDevIcons uses the KISS Workflow* to keep development momentum from being blocked by releases: Everything goes directly into the master after basic smoke test or review. master is basically dev or nightly branch, could break at anytime

Versions

VimDevIcons uses, at least as well as it can, Semantic Versioning.

Each release will have a branch and corresponding tag:

• branch MAJOR.MINOR.PATCH, e.g. 0.5.3
• tag vMAJOR.MINOR.PATCH v0.5.3

Automated Testing

todo

Issues

Submitted issues should follow the Issue Template as close as possible

New Release Workflow

• pull latest master branch
• create new versioned branch
  • "MAJOR.MINOR.PATCH"
  • e.g.

  git checkout -b 0.5.3

• merge any PRs that go in the milestone into the newly versioned branch
  • e.g.

  git checkout -b THE_PR_BRANCH_NAME master
  git pull https://github.com/THE_PR_BRANCH_URI THE_PR_REMOTE_BRANCH_NAME
  git checkout THE_VERSIONED_BRANCH
  git merge --no-ff THE_PR_BRANCH_NAME
  

• commit any general issue fixes/updates that go in the milestone
• update the readme if applicable
  • Make sure to update the versioned image reference paths (if minor or greater version changed)
• update the changelog
  • create new list item for the release
  • create new list items for each new merged PR, fix, update, etc
    • for PRs make sure to add @ for attribution to person who made the PR
    • prefix an appropriate verb in past tense for each (Updated, Added, Fixed, Improved, Changed)
• update internal version references in all .vim files that have them
• regenerate the vim doc automatically with html2vimdoc
  • e.g.

  VIMDEVICONS=~/projects/vim-devicons/
  VIMDEVICONSWIKI=~/projects/wiki.vim-devicons/
  VIMDEVICONSDESC="**VimDevIcons**\n\nAdds Icons to Your Plugins"
  cat ${VIMDEVICONSWIKI}ascii-logo.txt <(echo -e "${VIMDEVICONSDESC}") ${VIMDEVICONS}README.md <(echo -e "\n") ${VIMDEVICONSWIKI}Installation.md <(echo -e "\n") ${VIMDEVICONSWIKI}Usage.md <(echo -e "\n") ${VIMDEVICONSWIKI}Detailed-Features.md <(echo -e "\n") ${VIMDEVICONSWIKI}Extra-Configuration.md <(echo -e "\n") ${VIMDEVICONS}DEVELOPER.md <(echo -e "\n") ${VIMDEVICONSWIKI}FAQ-\&-Troubleshooting.md > /tmp/vim-devicons-combined-doc.md
  # replace html tags (particularly images we have in the wiki pages):
  sed -i 's/<[^>]*>//g' /tmp/vim-devicons-combined-doc.md
  # replace markdown badge/tags with text friendly plugin description
  sed -i 's/!\[.*\](.*)//g' /tmp/vim-devicons-combined-doc.md
  # for now do some basic search and replace to prevent issues with special characters:
  sed -i 's/✅//' /tmp/vim-devicons-combined-doc.md
  cd ~/vim-tools
  # NOTE: add '-v' option to html2vimdoc.py to debug
  html2vimdoc/bin/python ./html2vimdoc.py --file=devicons /tmp/vim-devicons-combined-doc.md > /tmp/webdevicons.txt
  cp /tmp/webdevicons.txt ${VIMDEVICONS}doc/webdevicons.txt

• push the new branch
  • git push -u origin <semver_based_branch_name>
• merge to master
  • git checkout master
  • git merge <semver_based_branch_name>
• create tag
  • "vMAJOR.MINOR.PATCH"
  • i.e. same as branch name but with prefixed with a 'v'
  • e.g. git tag v0.5.3
• push latest master and tag
  • git push origin master
  • git push --tags
• add new release on GitHub
  • basically copy and paste the version changes from the changelog.md
• Finally download release zip and upload to Vim Scripts (vim.org)

New Release VimScripts Upload

• Download latest release zip

• Rename the zip file slightly:

• Rename zip file from vim-devicons-x.x.x.zip to vim-devicons-vx.x.x.zip

• Make some necessary tweaks to a few files in the zip:

• Rename root folder

• Rename from vim-devicons-x.x.x to just vim-devicons

• Edit readme.md and add the follow mirror disclaimer to the very top followed by a new line:

  **NOTE: This is just a mirror, official repo is here: https://github.com/ryanoasis/vim-devicons**
  

• Save all changes and close the zip

• Re-open zip and verify changes saved

• Upload latest release zip to VimScripts: http://www.vim.org/scripts/script.php?script_id=5114

• For "script version" enter vx.x.x

• For "version comment" enter https://github.com/ryanoasis/vim-devicons/releases/tag/vx.x.x

Old release process for historical records (deprecated)

• We are no longer creating tags/releases because for Vim it really doesn't make sense as 99% of plugin users are going to simply clone from the master branch. The only thing we miss out on here is creating versioned releases and posting those to Vim Scripts (vim.org). I would like to restore this but only if it is through something like Github Actions so it happens automatically and does not slow down development.

• I try to group fixes into milestones/versions
  • If your bug or PR is not trivial it will likely end up in the next MINOR version
  • If your bug or PR is trivial or critical it will likely end up in the next PATCH version
• Most of the time PRs and fixes are not merged directly into master without being present on a new versioned branch
  • Sometimes for small items I will make exceptions to get the fix or readme change on master sooner but even after there will always be a versioned branch to keep track of each release

Code Standards

• Follow Vint
• Follow Google Vimscript Style Guide

*Based on GitFlow, GitHub Flow and a few others workflows