version to 2.6.0; rewrite docs for rolling release
This: - Changes version number everywhere I could find it. - Reworks get_version() to dispense with stable / dev division. - Rewrites CONTRIBUTING.md to describe a new release workflow. The development/release workflow stuff could use some thought. It's clunky at best. There's sort of an inherent tension between semver-style version numbers and the rolling release thing - maybe we should just use commit hash or something date-based? Still, it's a start.
This commit is contained in:
Brennen Bearnes
+49
-64
@@ -1,77 +1,62 @@
|
||||
# Contributing to Vimwiki
|
||||
# Contributing to VimWiki
|
||||
|
||||
# Filing a bug
|
||||
|
||||
Before filing a bug or starting to write a patch, check the latest development version from
|
||||
https://github.com/vimwiki/vimwiki/tree/dev to see if your problem is already fixed.
|
||||
Before filing a bug or starting to write a patch, check the latest development
|
||||
version from https://github.com/vimwiki/vimwiki/tree/dev to see if your problem
|
||||
is already fixed.
|
||||
|
||||
Issues can be filed at https://github.com/vimwiki/vimwiki/issues/ .
|
||||
Issues can be filed at https://github.com/vimwiki/vimwiki/issues/
|
||||
|
||||
# Git branching model
|
||||
|
||||
As of v2.6.0, VimWiki has adopted a rolling release model, while (for the
|
||||
moment) retaining specific version numbers. A release should be
|
||||
[prepared][#preparing-a-release] for every change or set of changes which merge
|
||||
to `dev`.
|
||||
|
||||
There are two permanent branches:
|
||||
1. `dev`: This is the default branch, and where changes are released. Tasks
|
||||
which are done in one or only a few commits go here directly. Always
|
||||
keep this branch in a working state. If the task you work on requires
|
||||
multiple commits, make sure intermediate commits don't make VimWiki
|
||||
unusable.
|
||||
2. `master`: This is a legacy branch, retained to avoid breaking existing
|
||||
checkouts of the plugin. It should be kept in sync with `dev`.
|
||||
|
||||
Large changes which require multiple commits may be authored in feature
|
||||
branches, and merged into `dev` when the work is done.
|
||||
|
||||
# Creating a pull request
|
||||
|
||||
If you want to provide a pull request on GitHub, please start from the `dev` branch, not from the
|
||||
`master` branch. (Caution, GitHub shows `master` as the default branch from which to start a PR.)
|
||||
If you want to provide a pull request on GitHub, start from the `dev` branch,
|
||||
not from the `master` branch.
|
||||
|
||||
Make sure to update `doc/vimwiki.txt` with the following information:
|
||||
Version bureaucracy:
|
||||
|
||||
1. Update the changelog to include, at the top of it, information on the new feature
|
||||
the PR introduces or the bug it is fixing as well as the PR number and related issue number
|
||||
if possible
|
||||
1. Pick a new version number according to [semver][semver] rules:
|
||||
`git tag vMAJOR.MINOR.PATCH`
|
||||
2. Update the version number at the top of `doc/vimwiki.txt`
|
||||
3. Update the version number at the top of `plugin/vimwiki.vim`
|
||||
4. Update the version number in `autoload/vimwiki/tags.vim`
|
||||
|
||||
Update `doc/vimwiki.txt` with the following information:
|
||||
|
||||
1. Update the changelog to include, at the top of it, information on the new
|
||||
feature the PR introduces or the bug it is fixing as well as the PR number
|
||||
and related issue number if possible.
|
||||
2. Add a help section to describe any new features or options.
|
||||
3. If you are a first time contributor add your name to the list of contributors.
|
||||
4. Add some non regression tests on:
|
||||
- The bug you fixed
|
||||
- The new feature you added
|
||||
- The API function you added or changed
|
||||
3. If you are a first time contributor add your name to the list of
|
||||
contributors.
|
||||
|
||||
**Testing:** Vimwiki uses [vader](https://github.com/junegunn/vader.vim) for unit tests and
|
||||
[vint](https://github.com/Kuniwak/vint) for linting. Any new PRs must add new tests and pass all
|
||||
linter checks. See the [test README](test/README.md) for more info.
|
||||
# Preparing a release
|
||||
|
||||
- In addition to the included tests, there are more example wikis that can be used for testing
|
||||
[here](https://github.com/vimwiki/testwikis).
|
||||
1. Set a tag with the version number in Git.
|
||||
2. `git push --tags`
|
||||
3. In GitHub, go to _Releases_ -> _Draft a new release_ -> choose the tag,
|
||||
convert the changelog from the doc to Markdown and post it there. Make
|
||||
plans to build an automatic converter and immediately forget this plan.
|
||||
4. If necessary, update `README.md` and the home page.
|
||||
5. For major changes: Tell the world.
|
||||
|
||||
# More info and advice for (aspiring) core developers
|
||||
|
||||
- Before implementing a non-trivial feature, think twice what it means for the user. We should
|
||||
always try to keep backward compatibility. If you are not sure, discuss it on GitHub.
|
||||
- Also, when thinking about adding a new feature, it should be something which fits into the
|
||||
overall design of Vimwiki and which a significant portion of the users may like. Keep in mind
|
||||
that everybody has their own way to use Vimwiki.
|
||||
- Keep the coding style consistent.
|
||||
- Test your changes. Keep in mind that Vim has a ton of options and the users tons of different
|
||||
setups. Take a little time to think about under which circumstances your changes could break.
|
||||
|
||||
## Git branching model
|
||||
|
||||
- There are two branches with eternal lifetime:
|
||||
1. `dev`: This is where the main development happens. Tasks which are done in one or only a few
|
||||
commits go here directly. Always try to keep this branch in a working state, that is, if the
|
||||
task you work on requires multiple commits, make sure intermediate commits don't make
|
||||
Vimwiki unusable (or at least push these commits at one go).
|
||||
2. `master`: This branch is for released states only. Whenever a reasonable set of changes has
|
||||
piled up in the `dev` branch, a [release is done](#preparing-a-release). After a release,
|
||||
`dev` has been merged into `master` and `master` got exactly one additional commit in which
|
||||
the version number in `plugin/vimwiki.vim` is updated. Apart from these commits and the
|
||||
merge commit from `dev`, nothing happens on `master`. Never should `master` merge into
|
||||
`dev`. When the users ask, we should recommend this branch for them to use.
|
||||
- Larger changes which require multiple commits are done in feature branches. They are based on
|
||||
`dev` and merge into `dev` when the work is done.
|
||||
|
||||
## Preparing a release
|
||||
|
||||
1. `git checkout dev`
|
||||
2. Update the changelog in the doc, nicely grouped, with a new version number and release date.
|
||||
3. Update the list of contributors.
|
||||
4. Update the version number at the top of the doc file.
|
||||
5. If necessary, update the Readme and the home page.
|
||||
6. `git checkout master && git merge dev`
|
||||
7. Update the version number at the top of plugin/vimwiki.vim.
|
||||
8. Set a tag with the version number in Git: `git tag vX.Y`
|
||||
9. `git push --tags`
|
||||
10. In GitHub, go to _Releases_ -> _Draft a new release_ -> choose the tag, convert the changelog
|
||||
from the doc to markdown and post it there. Make plans to build an automatic converter and
|
||||
immediately forget this plan.
|
||||
11. Tell the world.
|
||||
|
||||
<!-- vim: set tw=99 : -->
|
||||
[semver]: https://semver.org/
|
||||
|
||||
Reference in New Issue
Block a user