From d339ca0aa1d7e05aca9cb86790b3e1dccf73b9fb Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Tue, 14 Aug 2018 14:46:57 -0400 Subject: [PATCH 1/4] :ghost: populate missing links --- docs/how-we-work.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-we-work.md b/docs/how-we-work.md index 095404b7ba..5d6808a349 100644 --- a/docs/how-we-work.md +++ b/docs/how-we-work.md @@ -70,8 +70,8 @@ To introduce brand-new functionality into the package, follow this guide. ##### Process -1. On a feature branch, write a proposal as a markdown document beneath [`docs/rfcs`]() in this repository. Copy the [template]() to begin. Open a pull request. The RFC document should include: - * A description of the feature, writted as though it already exists; +1. On a feature branch, write a proposal as a markdown document beneath [`docs/rfcs`](/docs/rfcs) in this repository. Copy the [template](/docs/rfcs/000-template.md) to begin. Open a pull request. The RFC document should include: + * A description of the feature, written as though it already exists; * An analysis of the risks and drawbacks; * A specification of when the feature will be considered "done"; * Unresolved questions or possible follow-on work; From c73cf1e725266bf26a498f333889021f55ab11c1 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Tue, 14 Aug 2018 14:47:11 -0400 Subject: [PATCH 2/4] Mention the sprint board as a short-term planning tool. --- docs/how-we-work.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/how-we-work.md b/docs/how-we-work.md index 5d6808a349..683316a465 100644 --- a/docs/how-we-work.md +++ b/docs/how-we-work.md @@ -6,6 +6,10 @@ This is an attempt to make explicit the way that the core team plans, designs, a Process should serve the developers who use it and not the other way around. This is a live document! As our needs change and as we find that something here isn't bringing us the value we want, we should send pull requests to change it. +## Planning + +Our short-term planning is done in a series of [Project boards on this repository](https://github.com/atom/github/projects). Each project board is associated with a three-week period of time and a target version of the package. Our goal is to release a minor version of the package to atom/atom corresponding to the "Merged" column of its project board - in other words, it is less important to us to have an accurate Planned column before the sprint begins than it is to have an accurate Merged column after it's complete. + ## Kinds of change One size does not fit all, and accordingly, we do not prescribe the same amount of rigor for every pull request. These options lay out a spectrum of approaches to be followed for changes of increasing complexity and scope. Not everything will fall neatly into one of these categories; we trust each other's judgement in choosing which is appropriate for any given effort. When in doubt, ask and we can decide together. From f6556a2a6e9ddfe2a72d753c24bb12aa713bd8c8 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Tue, 14 Aug 2018 14:48:14 -0400 Subject: [PATCH 3/4] Mention adding PRs to the sprint planning board approximately everywhere --- docs/how-we-work.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/how-we-work.md b/docs/how-we-work.md index 683316a465..345f12ddd3 100644 --- a/docs/how-we-work.md +++ b/docs/how-we-work.md @@ -26,7 +26,7 @@ This includes work like typos in comments or documentation, localized work, or r ##### Process -1. Isolate work on a feature branch in the `atom/github` repository and open a pull request. Title-only pull requests are fine. If it's _really_ minor, like a one-line diff, committing directly to `master` is also perfectly acceptable. +1. Isolate work on a feature branch in the `atom/github` repository and open a pull request. Remember to add the pull request to the current sprint board. Title-only pull requests are fine. If it's _really_ minor, like a one-line diff, committing directly to `master` is also perfectly acceptable. 2. Ensure that our CI remains green across platforms. 3. Merge your own pull request; no code review necessary. @@ -38,8 +38,8 @@ Addressing unhandled exceptions, lock-ups, or correcting other unintended behavi 1. Open an issue on `atom/github` describing the bug if there isn't one already. 2. Identify the root cause of the bug and leave a description of it as an issue comment. If necessary, modify the issue body and title to clarify the bug as you go. -3. When you're ready to begin writing the fix, assign the issue to yourself and move it to the "in progress" column on the [short-term roadmap project](https://github.com/atom/github/projects/8). :rainbow: _This signals to the team and to the community that it's actively being addressed, and keeps us from colliding._ -4. Work on a feature branch in the `atom/github` repository and open a pull request. +3. When you're ready to begin writing the fix, assign the issue to yourself and move it to the "in progress" column on the current active sprint project. :rainbow: _This signals to the team and to the community that it's actively being addressed, and keeps us from colliding._ +4. Work on a feature branch in the `atom/github` repository and open a pull request. Remember to add the pull request to the current sprint project. 5. Write a failing test case that demonstrates the bug (or a rationale for why it isn't worth it -- but bias toward writing one). 6. Iteratively make whatever changes are necessary to make the test suite pass on that branch. 7. Merge your own pull request and close the issue. @@ -63,8 +63,8 @@ Major, cross-cutting refactoring efforts fit within this category. Our goals wit 2. Capture the context of the change in an issue, which can then be prioritized accordingly within our normal channels. * Should we stop or delay existing work in favor of a refactoring? * Should we leave it as-is until we complete other work that's more impactful? -3. When you're ready to begin refactoring, assign the issue to yourself and move it to "in progress" column on the [short-term roadmap project](https://github.com/atom/github/projects/8). -4. Work in a feature branch in the `atom/github` repository and open a pull request to track your progress. +3. When you're ready to begin refactoring, assign the issue to yourself and move it to "in progress" column on the current sprint project. +4. Work in a feature branch in the `atom/github` repository and open a pull request to track your progress. Remember to add the pull request to the current sprint project board. 5. Iteratively change code and tests until the change is complete and CI builds are green. 6. Merge your own pull request and close the issue. @@ -83,7 +83,7 @@ To introduce brand-new functionality into the package, follow this guide. * The acceptance criteria for the RFC itself, as chosen by your current understanding of its scope and impact. Some options you may use here include _(a)_ you're satisfied with its state; _(b)_ the pull request has collected a predetermined number of :+1: votes from core team members; or _(c)_ unanimous :+1: votes from the full core team. 2. @-mention @simurai on the open pull request for design input. Begin hashing out mock-ups, look and feel, specific user interaction details, and decide on a high-level direction for the feature. 3. The RFC's author is responsible for recognizing when its acceptance criteria have been met and merging its pull request. :rainbow: _Our intent here is to give the feature's advocate the ability to cut [bikeshedding](https://en.wiktionary.org/wiki/bikeshedding) short and accept responsibility for guiding it forward._ -4. Work on the RFC's implementation is performed in one or more pull requests. +4. Work on the RFC's implementation is performed in one or more pull requests. Remember to add each pull request to the current sprint project. * Consider gating your work behind a feature flag or a configuration option. * Write tests for your new work. * Optionally [request reviewers](#how-we-review) if you want feedback. Ping @simurai for ongoing UI/UX considerations if appropriate. From f24277a0898648c5f083d8b7446599cba8b01d1b Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Tue, 14 Aug 2018 15:22:27 -0400 Subject: [PATCH 4/4] Update publishing instructions to include a QA pass and backporting --- docs/how-we-work.md | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/how-we-work.md b/docs/how-we-work.md index 345f12ddd3..54b763f54a 100644 --- a/docs/how-we-work.md +++ b/docs/how-we-work.md @@ -118,20 +118,28 @@ When finalizing your review: The github package ships as a bundled part of Atom, which affects the way that our progress is delivered to users. After using `apm` to publish a new version, we also need to add a commit to [Atom's `package.json` file](https://github.com/atom/atom/blob/master/package.json#L114) to make our work available. -When the team is preparing to ship a new version of Atom, run `apm publish minor` and update `package.json` on Atom's master branch to reference the new version. This will ship our work to Atom's [beta channel](https://atom.io/beta) and allow a smaller subset of our users to discover regressions before we release it to the full Atom user population. - -When you update Atom's `package.json`, make sure you wait for Atom to build before you merge your changes. In particular, we've had issues with snapshot tests. You can either do `apm publish pre` on the branch with the fix, then modify `package.json` in your local atom and try a `script/build`. Or you can open a pull requests and let the CI tests run for you. - -When you've merged substantial new functionality, consider running `apm publish minor` and updating `package.json` on Atom's master branch outside of the Atom release cycle, to give the rest of the Atom team time to dogfood the change internally and weigh in with opinions. - -After shipping a minor version release for either of the above situations, create and push a release branch from that version's tag: - -```sh -$ apm publish minor -version 0.11.0 -$ git branch 0.11-releases && git push -u origin 0.11-releases -``` - -When you merge a fix for a bug, cherry-pick the merge commit onto to the most recent release branch, then run `apm publish patch` and update `package.json` on the most recent beta release branch on the `atom/atom` repository. This will ensure bug fixes are delivered to users on Atom's stable channel as part of the next release. - -When you merge a fix for a **security problem**, a **data loss bug**, or fix a **crash** or a **lock-up** that affect a large portion of the user population, cherry-pick the merge commit onto the most recent beta _and_ stable release branches of atom/github that contain the bug, then run `apm publish patch` on both and update `package.json` on the affected release branches on the `atom/atom` repository. Consider advocating for a hotfix release of Atom to deliver these fixes to the user population as soon as possible. +At the end of each development sprint: + +1. _In your atom/github repository:_ run `apm publish preminor` to create the first prerelease version or `apm publish prerelease` to increment an existing prerelease version. Note the generated version number and ensure that it's correct. If the currently deployed version is `v0.19.2`, the first prerelease should be `v0.20.0-0`; if the existing prerelease is `v0.20.0-0`, the next prerelease should be `v0.20.0-1`. +2. _In your atom/atom repository:_ create a new branch and edit `package.json` in its root directory. Change the version of the `"github"` entry beneath `packageDependencies` to match the prerelease you just published. +3. _In your atom/atom repository:_ Run `script/build --install`. This will update Atom's `package-lock.json` files and produce a local development build of Atom with your prerelease version of atom/github bundled. + * :boom: _If the build fails,_ correct any bugs and begin again at (1) with a new prerelease version. +4. Run `apm uninstall github` and `apm uninstall --dev github` to ensure that you don't have any [locally installed atom/github versions](/CONTRIBUTING.md#living-on-the-edge) that would override the bundled one. +5. _In your atom/atom repository:_ Push your branch to atom/atom and open a pull request to start running CI. +6. Create a [QA issue](https://github.com/atom/github/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Aquality) in the atom/github repository. Its title should be "_prerelease version_ QA Review" and it should have the "quality" label applied. Populate the issue body with a checklist containing the pull requests that were included in this release; these should be the ones in the "Merged" column of the project board. Omit pull requests that don't have verification steps (like renames, refactoring, or dependency upgrades, for example). Add a final entry for a clean CI check on the atom/atom pull request. +7. Use your `atom-dev` build to verify each and check it off the list. + * :boom: _If verification fails,_ note the failure in an issue comment. Close the issue. Correct the failure with more work in the current sprint board, then begin again at (1). + * :white_check_mark: _Otherwise,_ comment in and close the issue, then continue. +8. _In your atom/github repository:_ run `apm publish minor` to publish the next minor version. +9. _In your atom/github repository:_ create a release branch for this minor version with `git checkout -b 0.${MINOR}-releases`. Push it to atom/github. +9. _In your atom/atom repository:_ update the version of the `"github"` entry beneath `packageDependencies` in `package.json` to match the published minor version. Run `script/build` to update `package-lock.json` files. Commit and push these changes. +10. When the CI build for your atom/atom pull request is successful, merge it. + +Now cherry-pick any suitably minor or low-risk bugfix PRs from this release to the previous one: + +1. _In your atom/github repository:_ run `git checkout 0.${LASTMINOR}-releases`. For example, if the current release is v0.19.0, the target release branch should be `0.18-releases`. +2. _In your atom/github repository:_ identify the merge SHA of each pull request eligible for backporting. One way to do this is to run `git log --oneline --first-parent master ^HEAD` and identify commits by the "Merge pull request #..." commit messages. +3. _In your atom/github repository:_ cherry-pick each merge commit onto the release branch with `git cherry-pick -m 1 ${SHA}`. Resolve any merge conflicts that arise. +4. Follow the instructions above to publish a new patch version of the package. (Use `apm publish prepatch` / `apm publish prerelease` to generate the correct version numbers.) + +For _really_ urgent fixes, like security problems, data loss bugs, or frequently occurring crashes or lock-ups, consider repeating the cherry-pick instructions for the minor version sequence published on Atom stable, and advocating for an Atom hotfix to deliver it as soon as possible.