docs/breaking_changes.md

   1 # Breaking Changes
   2
   3 This document describes QMK's Breaking Change process. A Breaking Change is any change which modifies how QMK behaves in a way that in incompatible or potentially dangerous. We limit these changes so that users can have confidence that updating their QMK tree will not break their keymaps.
   4
   5 The breaking change period is when we will merge PR's that change QMK in dangerous or unexpected ways. There is a built-in period of testing so we are confident that any problems caused are rare or unable to be predicted.
   6
   7 ## What has been included in past Breaking Changes?
   8
   9 * [2019 Aug 30](ChangeLog/20190830.md)
  10
  11 ## When is the next Breaking Change?
  12
  13 The next Breaking Change is scheduled for Nov 29.
  14
  15 ### Important Dates
  16
  17 * [ ] 2019 Oct 04 - `future` is created. It will be rebased weekly.
  18 * [ ] 2019 Nov 01 - `future` closed to new PR's.
  19 * [ ] 2019 Nov 01 - Call for testers.
  20 * [ ] 2019 Nov 27 - `master` is locked, no PR's merged.
  21 * [ ] 2019 Nov 29 - Merge `future` to `master`.
  22 * [ ] 2019 Nov 30 - `master` is unlocked. PR's can be merged again.
  23
  24 ## What changes will be included?
  25
  26 To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged.
  27
  28 If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted.
  29
  30 Criteria for acceptance:
  31
  32 * PR is complete and ready to merge
  33 * PR has a ChangeLog
  34
  35 # Checklists
  36
  37 This section documents various processes we use when running the Breaking Changes process.
  38
  39 ## Rebase `future` from `master`
  40
  41 This is run every Friday while `future` is open.
  42
  43 Process:
  44
  45 ```
  46 cd qmk_firmware
  47 git checkout master
  48 git pull --ff-only
  49 git checkout future
  50 git rebase master
  51 git push --force
  52 ```
  53
  54 ## 8 Weeks Before Merge
  55
  56 * `qmk_firmware` git commands
  57     * [ ] `git checkout master`
  58     * [ ] `git pull --ff-only`
  59     * [ ] `git checkout -b future`
  60     * [ ] Edit `readme.md`
  61         * [ ] Add a big notice at the top that this is a testing branch.
  62         * [ ] Include a link to this document
  63     * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
  64     * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
  65     * [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
  66     * [ ] `git push origin future`
  67     * [ ] `git push --tags`
  68 * GitHub Actions
  69     * [ ] Switch all [breaking_change PR's](https://github.com/qmk/qmk_firmware/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Abreaking_change) to `future`
  70     * [ ] Any that have a ChangeLog entry may be merged immediately.
  71
  72 ## 4 Weeks Before Merge
  73
  74 * `future` is now closed to new PR's, only fixes for current PR's may be merged
  75 * Post call for testers
  76     * [ ] Discord
  77     * [ ] GitHub PR
  78     * [ ] https://reddit.com/r/olkb
  79
  80 ## 1 Week Before Merge
  81
  82 * Announce that master will be closed from <2 Days Before> to <Day of Merge>
  83     * [ ] Discord
  84     * [ ] GitHub PR
  85     * [ ] https://reddit.com/r/olkb
  86
  87 ## 2 Days Before Merge
  88
  89 * Announce that master is closed for 2 days
  90     * [ ] Discord
  91     * [ ] GitHub PR
  92     * [ ] https://reddit.com/r/olkb
  93
  94 ## Day Of Merge
  95
  96 * `qmk_firmware` git commands
  97     * [ ] `git checkout future`
  98     * [ ] `git pull --ff-only`
  99     * [ ] `git rebase origin/master`
 100     * [ ] Edit `readme.md`
 101         * [ ] Remove the notes about `future`
 102     * [ ] Roll up the ChangeLog into one file.
 103     * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
 104     * [ ] `git push origin future`
 105 * Github Actions
 106     * [ ] Create a PR for `future`
 107     * [ ] Make sure travis comes back clean
 108     * [ ] Merge `future` PR