document rule branches

[williballenthin]

add documentation to the readmes explaining mandiant/capa-rules#556

closes #764
closes #529

Checklist

• No CHANGELOG update needed

• No new tests needed

• No documentation update needed

[github-actions]

Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning to the master (unreleased) section of CHANGELOG.md. If no CHANGELOG update is needed add the following to the PR description: [x] No CHANGELOG update needed

CHANGELOG updated or no update needed, thanks! 😄

[mr-tz]

I've pushed some changes to this branch and added a few comments based on what Ana suggested earlier this week.

[mr-tz]

I've fixed/updates the tags on capa-rules

Before

$ git --no-pager tag -l -n
v1              Update rules number badge
v1.0.0          v1.0.0
v1.1.0          Update rules number badge
v1.2.0          v1.2.0
v1.3.0          Merge pull request #120 from fireeye/fix/comment-out-block-description
v1.4.0          Update rules number badge
v1.5.0          Update rules number badge
v1.5.1          v1.5.1
v1.6.0          v1.6.0
v1.6.1          Update rules number badge
v2              bypass UAC via ICMLuaUtil: fix ATT&CK mapping
v2.0.0          https://github.com/fireeye/capa/releases/v2.0.0
v3              Merge pull request #536 from mandiant/call5-update
v3.0.0          https://github.com/fireeye/capa/releases/v3.0.0
v3.0.1          https://github.com/fireeye/capa/releases/v3.0.1
v3.0.2          https://github.com/mandiant/capa/releases/v3.0.2
v3.0.3          https://github.com/mandiant/capa/releases/v3.0.3
v3.1.0          https://github.com/mandiant/capa/releases/v3.1.0
v3.2.0          https://github.com/mandiant/capa/releases/v3.2.0

After

$ git --no-pager tag -l -n
v1              https://github.com/mandiant/capa/releases/v1.6.3
v1.0.0          https://github.com/mandiant/capa/releases/v1.0.0
v1.1.0          https://github.com/mandiant/capa/releases/v1.1.0
v1.2.0          https://github.com/mandiant/capa/releases/v1.2.0
v1.3.0          https://github.com/mandiant/capa/releases/v1.3.0
v1.4.0          https://github.com/mandiant/capa/releases/v1.4.0
v1.5.0          https://github.com/mandiant/capa/releases/v1.5.0
v1.5.1          https://github.com/mandiant/capa/releases/v1.5.1
v1.6.0          https://github.com/mandiant/capa/releases/v1.6.0
v1.6.1          https://github.com/mandiant/capa/releases/v1.6.1
v2              https://github.com/mandiant/capa/releases/v2.0.0
v2.0.0          https://github.com/mandiant/capa/releases/v2.0.0
v3              https://github.com/mandiant/capa/releases/v3.2.0
v3.0.0          https://github.com/mandiant/capa/releases/v3.0.0
v3.0.1          https://github.com/mandiant/capa/releases/v3.0.1
v3.0.2          https://github.com/mandiant/capa/releases/v3.0.2
v3.0.3          https://github.com/mandiant/capa/releases/v3.0.3
v3.1.0          https://github.com/mandiant/capa/releases/v3.1.0
v3.2.0          https://github.com/mandiant/capa/releases/v3.2.0

Used commands (see first reference)

git checkout v1.2.0
# delete local
git tag -d v1.2.0
# delete remote
git push origin :refs/tags/v1.2.0
# see date
echo $(git show --format=%aD | head -1)
# use date from commit
GIT_COMMITTER_DATE="$(git show --format=%aD | head -1)" git tag -a v1.2.0 -m "https://github.com/mandiant/capa/releases/v1.2.0"
# OR use hard-coded date
GIT_COMMITTER_DATE="2020-09-01 06:13:17 +0200" git tag -a v1.2.0 -m "https://github.com/mandiant/capa/releases/v1.2.0"
git push --tags

References

• https://stackoverflow.com/questions/21738647/change-date-of-git-tag-or-github-release-based-on-it
• https://git-scm.com/docs/git-tag
• https://stackoverflow.com/questions/49283734/why-isnt-my-tag-listed-when-i-checkout-with-git-gui#49286861

[williballenthin]

I'm really happy with the decisions and work that were made while I was out - thank you!

My only feedback is that, personally, I don't think of tags as things that change. I think of branches as things that get updated over time with new content. So it feels like v1/v2/v3 are more like branches. But, feelings aren't enough :-)

So, Im happy with the changes here and think we should go forward with them. If they don't work over the next releases, we can always update our processes again.

[mr-tz]

Per the default tags should not change, so I'm fine using branches if we can update them automatically like proposed in this PR for tags currently: https://github.com/mandiant/capa/pull/1006/files#diff-84dff8d1094ca39c02ac0e48d951ca22f4da29c76b50ae517f5bd2d50f94c2f6R25

TODO:

• auto-update branch (or leave on tag)
• accept/reject suggestions
• use version code / help output
• ready for review
• merge

[williballenthin]

looks great, lets merge this soon.

(apparently i cannot approve my own PR, but please consider it approved)