diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9fe4cf7b0f6d8ffc4ae9e2e5923daf8ceb32d7b1..0c29389b882991dbfc70e956ecbbe7e98cc66b06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -134,27 +134,16 @@ For feature proposals for EE, open an issue on the [issue tracker of EE][ee-tracker]. In order to help track the feature proposals, we have created a -[`feature proposal`][fpl] label. For the time being, users that are not members -of the project cannot add labels. You can instead ask one of the [core team] +[`feature proposal`][fpl] label. Users that are not members +of the project can't add labels. You can instead ask one of the [core team] members to add the label `feature proposal` to the issue or add the following code snippet right after your description in a new line: `~"feature proposal"`. Please keep feature proposals as small and simple as possible, complex ones -might be edited to make them small and simple. +might be edited to make them small and simple. See also +[the product guidelines on creating good proposals for changes][product-guidelines]. -You are encouraged to use the template below for feature proposals. - -``` -## Description including problem, use cases, benefits, and/or goals - -## Proposal - -## Links / references -``` - -For changes in the interface, it can be helpful to create a mockup first. -If you want to create something yourself, consider opening an issue first to -discuss whether it is interesting to include this in GitLab. +[product-guidelines]: PRODUCT.md ### Issue tracker guidelines diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000000000000000000000000000000000000..8fe1991c888c7113da49715ef71e91ba3b351299 --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,54 @@ +# Product + +At GitLab, we introduce changes in small, rapid iterations. Changes should never take away from the experience of the end user or introduce extra steps in workflows. + +## What to suggest + +GitLab wants to bring your products _frictionless from idea to production_. This means that _anyone_ involved with the lifecycle of a product should be able to use GitLab _and do so happily_. + +### Minimally Viable Proposal + +It’s great to have big ideas, but big ideas are hard to tackle at once. That’s why we expect you to write a minimally viable proposal. + +A MVP is a proposal for a change in its very simplest form. Starting simple means we can iterate based on our experience and feedback from others. It also means we can build almost anything with a single release. + +### No options! + +Your proposal should not introduce options. Options increase code, product complexity. They make GitLab harder to use, unfriendlier to new _and_ returning users and harder to contribute to. + +Don’t introduce options. + +## Writing Issues + +At GitLab, everything starts with an issue. Anyone can and should create issues. When creating or editing an issue, it is your job to shape this into a form that is understandable for everyone. + +Use the template below to bring any issue into shape. If you’re editing an existing issue, it is a good idea to keep the original contents below. + +``` +## Description including problem, use cases, benefits, and/or goals + +## Proposal + +## Links / references +``` + +It is imperative that you keep the word count as low as possible. Don’t diverge, don’t ramble. People tend to not read anything more than a handful of sentences. + +Adding drawings, mockups, sketches is encouraged. + +Any engineer familiar with GitLab should be able to get to work based on your issue. It’s fine to leave some details to the engineer to solve, but work out anything that you think can be a problem. + +## The issue body is the single source of truth + +Whenever changes are made to the planned change, make sure that the issue body reflects these changes, it is the single source of truth. + +An engineer working on an issue is not expected to first read through a long comment thread before having to start. + +## Scheduling issues + +Scheduling issues happens according to milestones. This has to be done in close collaboration with engineering. + +## Labels + +Issues should have relevant labels applied. For most changes, this would be +~"feature proposal". See [PROCESS](PROCESS.md) for more details.