Add documentation about big MR and refactors
As discussed with @jschatz1 it is not sustainable to review a MR with 100 file changes: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12069 or to take 2-3 months to refactor something.
We need to remove from our docs the section about big MR and how we should merge smaller MRs into a big one. It was discussed in a retrospective that this section goes against the direction we want to move: https://docs.gitlab.com/ce/development/fe_guide/index.html#divide-a-big-feature-into-small-merge-requests
We need to add to our docs a new way of doing this: piece meal:
(As done in CI code refactor into Vue in the past)
- Plan ahead: Identify all Vue components needed.
- Start with the smallest component you can find.
- Open a MR with the smallest component and tests for it.
- Get it reviewed and merge into master. It won't be used right away.
- Do steps 2 to 4 for all reusable components
- Once all the components are reviewed and merged into master, start a MR with your Vue App (Store - Vuex or not, Service and main file) 6.1 This MR should include tests for the new application (note that all the used components are already in master will full coverage)
Result: Smaller MRs, smaller iterations; fast reviews; we will ship things faster
Example of this done in the past:
- Header section in Pipelines Detail View and Job Detail view
- The header is the same component.
- First we identified all the components needed.
- We created a MR for the ci status badge and merged into master
- We created a MR for the header component 100% reusable between Pipelines and Job Details view with tests and merged into master
- We created a MR for the Pipelines view were we started a vue app and used the component.
- We did the same for the Job view, were we started a vue app and used the already merged component.
This process was done by me and reviewed by @iamphill. The process of identifying all the components was made previously and also reviewed by @iamphill and @jschatz1.
This process allowed us to ship things faster and to have smaller MR. Both @iamphill and @ayufan can confirm this.
EDIT:
This process started earlier: (with links)
-
we identified what needed to be vue and the components that we would need (page 3 and 4) https://docs.google.com/a/gitlab.com/document/d/13-gmGPbdkPZjHynwD44TPYj_6LJED9JW1ec6y_hVe0g/edit?usp=sharing
-
First step was to create the smallest components we needed across all components: The CI Status Icons and the badge: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11235
-
We then started with the graph, and in the first release only did the graph: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10878 (and we saw it was still to big)
-
Next release we created the header in vue: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11726
-
Next step we needed to transform the pipelines detail page into a vue app instead of having two apps, so we could use both the graph and the header with the same polling data: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11732/diffs (this topic was presented in vue conf on how we deal with big refactors: http://filipa.gitlab.io/vue_conf_2017/vue_gitlab_2017.pdf)
-
We did the same for the job's page (first the smallest ones, then the mediator to use them all)
These pages are still not entirely in Vue, and the plan is to make it so we can have it all in real time.
By doing it like this we were able to actually ship something, if we had aimed to the all page it would not have been merged in one cycle and the could would have been harder to review