Development Workflow - ryanoasis/vim-devicons GitHub Wiki
Theses details are for contributors not general VimDevIcon plugin users 😉
Table of Contents:
- Prerequisites
- KISS Workflow*
- Branch Conventions
- Versions
- Automated Testing
- Issues
- New Release Workflow
- New Release Vimscripts Upload
- Code Standards
- 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
This describes the overall workflow and release methodology for the VimDevIcons project.
- Keep contributor(s) barrier to entry as low as possible
- "Release early, release often"
- KISS (Keep it simple, stupid)
-
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
- Tags will follow format of:
- We are no longer creating tags/releases (more info)
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
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
todo
Submitted issues should follow the Issue Template as close as possible
- 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)
- for PRs make sure to add
- 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 taggit push origin master
git push --tags
- add new release on GitHub
- basically copy and paste the version changes from the
changelog.md
- basically copy and paste the version changes from the
- Finally download release zip and upload to Vim Scripts (vim.org)
-
Download latest release zip
-
Rename the zip file slightly:
-
Rename zip file from
vim-devicons-x.x.x.zip
tovim-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 justvim-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
- 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
- Follow Vint
- Follow Google Vimscript Style Guide
*Based on GitFlow, GitHub Flow and a few others workflows