From f35e31168dabad71a6f42e1320a66a6ea007b1dc Mon Sep 17 00:00:00 2001 From: Christoph Wurst Date: Tue, 28 Dec 2021 16:08:43 +0100 Subject: [PATCH] Drop Kanban development process, rework common labels The Kanban dev process was used many years ago but never in Nextcloud. Therefore the process description is not just outdated but misleading. We still use the labels, albeit their description was mildly outdated. They were restructured and grouped for better comprehensibility. Signed-off-by: Christoph Wurst --- .../getting_started/codingguidelines.rst | 36 ++- .../prologue/development_process.rst | 268 ------------------ developer_manual/prologue/index.rst | 1 - 3 files changed, 21 insertions(+), 284 deletions(-) delete mode 100644 developer_manual/prologue/development_process.rst diff --git a/developer_manual/getting_started/codingguidelines.rst b/developer_manual/getting_started/codingguidelines.rst index 2645e9127..fa5e0861e 100644 --- a/developer_manual/getting_started/codingguidelines.rst +++ b/developer_manual/getting_started/codingguidelines.rst @@ -24,24 +24,30 @@ We assign labels to issues and pull requests to make it easy to find them and to The most important labels and their meaning: -* #backport-request - the pull requests also needs to be applied to older Nextcloud versions -* #bug - this issue is a bug -* #enhancement - this issue is a feature request/idea for improvement of Nextcloud -* #design - this needs help from the design team or is a design-related issue/pull request -* #technical debt - this issue or PR is about `technical debt `_ -* #good first issue - these are issues which are relatively easy to solve and ideal for people who want to learn how to code in Nextcloud -* #needs info - this issue needs further information from the reporter, see :doc:`../../prologue/bugtracker/triaging` -* #high #medium #low signify how important the bug is. * Tags showing the state of the issue or PR, numbered 0-4: - * 0\. Needs triage - ready to start development on this - * 1\. to develop - ready to start development on this - * 2\. developing - development in progress - * 3\. to review - ready for review - * 4\. to release - reviewed PR that awaits unfreeze of a branch to get merged -* Feature tags: #feature: something. These tags indicate the features across apps and components which are impacted by the issue or which the PR is related to + * ``0. to triage`` - issue or feature request needs to get triaged and approved for development + * ``1. to develop`` - ready to start development on this + * ``2. developing`` - development in progress + * ``3. to review`` - ready for review + * ``4. to release`` - reviewed PR that awaits unfreeze of a branch to get merged or has pending CI jobs + * ``needs info`` - this issue needs further information from the reporter, see :doc:`../../prologue/bugtracker/triaging`. This tag is typically combined with ``0. to triage`` to signal a bug report is not confirmed yet or a feature request has not been approved. -If you want a label not in the list above, please first discuss on the mailing list. +* Tags showing the type of issue or PR + + * ``bug`` - this issue is a bug + * ``enhancement`` - this issue is a feature request/idea for improvement of Nextcloud + * ``technical debt`` - this issue or PR is about `technical debt `_ + +* Tags that classify an issue or PR + + * ``high``, ``medium`` and ``low`` – signify how important the bug is. + * ``regression`` - something that worked in a previous release but is now not working as expected or missing. + * ``feature: *``, e.g. ``feature: dav`` – these tags group tickets of specific feature or subsystems. + * ``design`` - this needs help from the design team or is a design-related issue/pull request + * ``good first issue`` - these are issues which are relatively easy to solve and ideal for people who want to learn how to code in Nextcloud + +* ``backport-request`` - the pull requests also needs to be applied to older Nextcloud versions. This tag is typically assigned by automation. Coding ------ diff --git a/developer_manual/prologue/development_process.rst b/developer_manual/prologue/development_process.rst deleted file mode 100644 index 08d63f9fe..000000000 --- a/developer_manual/prologue/development_process.rst +++ /dev/null @@ -1,268 +0,0 @@ -=================== -Development process -=================== - -This chapter contains a lot of information about the development process the -Nextcloud community tries to follow, so please take your time to digest all the -information. In any case remember this page as the documentation on how it -should be done. Nothing here is set in stone, so if you think something should -be changed please discuss it on the `forums`_. - -The labels ----------- - -The following list shows what the labels mean in the life-cycle and will -hopefully help you decide how to label an issue. - -Backlog -^^^^^^^ - -Why do we have it? - To keep us focused on finishing issues that we started, new issues will be - hidden in this column. In HuBoard you can see the list of things that we could - think about by clicking the small arrow in the top left corner of the concept - column header. - -What does a developer think? - "Maybe later." - -When can I pull? - Since this is the bucket for whatever might be done you should only pick - issues from the backlog when there is no other issue that you can work on. It - is more important to finish an issue currently on the Kanban board than to - pull a new one into the flow because only released issues have a value to our - users! - -Who is Assigned? - Either a maintainer feels directly responsible for the issue and assigns - himself or the gatekeeper (the guys having a look at unassigned bugs) will try - to determine the responsible developer. - -Concept -^^^^^^^ - -Why do we have it? - Our think before you act phase serves two purposes. A Bug is in the concept - phase while we are trying to figure out why something is broken (analysis). An - Enhancement is in the concept phase until we have decided how to implement it - (design). - -What does a developer think? - "I’ll write a Scenario for our BDD in `Gherkin`_ and post it as a comment. I - can always look at the `existing ones`_ to get an inspiration how to phrase - them as `“Given … when … then …“`_" - -When can I pull? - As long as you think and discuss on how to implement an enhancement or how to - solve a bug you should leave the concept label assigned. Two things should be - documented in a comment to the issue before moving it to the "To develop" - step: - - * At least one Scenario – written in Gherkin – that tells you and the tester - when the issue is ready to be released. - * A concept describing the planned implementation. This can be as simple as - a “this just needs changes to the login screen CSS” or so complex that you - link to a blog entry somewhere else. - -Who is Assigned? - The maintainer that feels responsible for the issue. - -To develop -^^^^^^^^^^ - -Why do we have it? - Now that we have a plan, any developer can pick an issue from this column and - start implementing it. If the issue is also marked with Junior Job this might - be a good starting point for new developers. - -What does a developer think? - "Nice! I can safely implement it that way because more than one person has put - their brain to the task of coming up with a good solution. Here! Me! I’ll do - it!" - -When can I pull? - If you feel like diving into the code and getting your hands dirty you should - look for issues with this label. In the comments, there should be a Gherkin - scenario to tell you when you are done and a concept describing how to - implement it. Before you start move the issue to the “Developing” step by - assigning the "4 – Developing" label. - -Who is Assigned? - No one. Especially not if you are working on something else! - -Developing -^^^^^^^^^^ - -Why do we have it? - This is where the magic happens. If it’s a Bug the fix will be submitted as a - PULL REQUEST to the master or corresponding stable branch. If its an - Enhancement code will be committed to a feature branch. - -What does a developer think? - "You know, I’m at it. By the way, I’ll also write `unit tests`_. When I’m done - I’ll push the issue with a commit containing "push GH-#" where # is the issue - number. If I have an idea of who should review it I can also notify them with - @githubusername" - -When can I pull? - As long as you are writing code for the issue or if any unit test fails you - should leave the “4 – Developing” label assigned. Two things should have been - implemented before moving the issue to the “To review” step: - - * The enhancement or bug in question - * Unit tests for the changed and added code. - -Who is Assigned? - The most active developer should assign himself. - -To review -^^^^^^^^^ - -Why do we have it? - Instead of directly committing to master we agree that **a second set of eyes - will spot bugs** and increase our code quality and give us an opportunity to - learn from each other. See also our documentation about :ref:`code-reviews` - -What does a developer think? - "I’ll check the Scenario described earlier works as expected. If necessary - I’ll update the related Gherkin Scenarios. `Drone`_ will test the scenario - on all kinds of platforms, Web server and database combinations with - `Cucumber`_." - -When can I pull? - If you feel like making sure an issue works as expected you should look for - issues with this label. In the comments you should find a Gherkin scenario that - can be used as a checklist for what to try. Before you start move the issue to - the “Reviewing” step by assigning the “6 – Reviewing” label. - -Who is Assigned? - No one. Especially not if you are working on something else! - -Reviewing -^^^^^^^^^ - -Why do we have it? - With the Gherkin Scenario from the Concept Phase reviewers have a checklist to - test if a Bug has been solved and if an Enhancement works as expected. **The - most eager reviewer we have is Drone**. When it comes to testing they soldier - on going through the different combinations of platform, Web server and - database. - -What does a developer think? - "Damn! If I had written the Gherkin Scenarios and Cucumber Step Definitions I - could leave the task of testing this on the different combinations of platform, - Web server and database to Drone. I’ll miss something when doing this - manually.* - -When can I pull? - As long as you are reviewing the issue you should leave the "6 – - Reviewing" label assigned. Before moving the issue to the "To review" step the - issue should have been resolved, meaning that not only the issue has been - implemented but also no other functionality has been broken. - -Who is Assigned? - The most active reviewer should assign himself. - -To release -^^^^^^^^^^ - -Why do we have it? - This is a list of issues that will make it into the next release. It serves - as a source for the changelog, as well as a reminder of the work we can already - be proud of. - -What does a developer think? - "Look at all the shiny things we will release with the next version of - Nextcloud!" - -When can I pull? - This is the last step of the Kanban board. When the Release finally happens - the issue will be closed and removed from the board. - -Who is Assigned? - No one. - - -While we stated before that we push issues to the next column, we can -of course move the item back and forth arbitrarily. Basically you can drag the -issue around in the HuBoard or just change the label when viewing the issue in -the GitHub. - -Reviewing considered impossible? --------------------------------- - -How can you possibly review an issue when it requires you to test various -combinations of browsers, platforms, databases and maybe even app combinations? -Well, you can’t. But you can write a Gherkin scenario that can be used to write -an automated test that is executed by Drone on every commit to the main -repositories. If for some reason Drone cannot be used for the review you will -find yourself in the very uncomfortable situation where you release half tested -code that will hopefully not eat user data. Seriously! Write Gherkin scenarios! - -Other labels ------------- - -Priority labels -^^^^^^^^^^^^^^^ - -* Panic should be used with caution. It is reserved for Bugs that would result - in the loss of files or other user data. An Enhancement marked as Panic is - expected by Nextcloud users for the next release. In either case an open Panic - issue will prevent a release. - -* Attention is not as hard as Panic. But we really want this in the next release - and will dedicate more effort for it. But if we think the issue is not ready - for the next release we will postpone it to the next one. - -* Regression is something that worked in a previous release but is now not - working as expected or missing. If a certain functionality is up for code - refactoring, the developer should describe all possible use cases as a Gherkin - scenarios beforehand, so that any scenarios that isn’t implemented before the - required milestone can be marked as a regression. If a regression is found - after a release, the reporter – or the developer triaging the issue – should - describe the functionality as a Gherkin scenario and either fix it or assign - it to the developer in charge of that part. - -App labels -^^^^^^^^^^ - -In the apps repository there are labels like ``app:gallery`` and -``app:calendar``. The ``app:`` prefix is used to allow developers to filter -issues related to a specific app. - -Resolution status -^^^^^^^^^^^^^^^^^ - -* Fixed – Should be assigned to issues in to Release -* Won’t fix – Reason is given as a comment -* Duplicate – Corresponding bug is given in a comment (using #guthubissuenumber) - -Misc labels -^^^^^^^^^^^ - -* Needs info – Either from a developer or the bug reporter. This is nearly as - severe as Panic, because no further action can be taken -* L18n – A translation issue; go see our `Transifex`_ -* Junior Job – The issue is considered a good starting point to get involved in Nextcloud development - -Milestones equal releases -------------------------- - -Releases are planned via milestones which contain all the Enhancements and Bugs -that we plan to release when the Deadline is met. When the Deadline approaches -we will push new Enhancement request and less important bugs to the next -milestone. This way a milestone will upon release contain all the issues that -make up the changelog for the release. Furthermore, HuBoard allows us to filter -the Kanban board by Milestone, making it especially easy to focus on the current -Release. - -.. _kanban board: https://en.wikipedia.org/wiki/Kanban_board -.. _forums: https://help.nextcloud.com -.. _Gherkin: https://github.com/cucumber/cucumber/wiki/Gherkin -.. _existing ones: https://github.com/nextcloud/server/tree/master/build/integration/features -.. _“Given … when … then …“: https://github.com/cucumber/cucumber/wiki/Given-When-Then -.. _unit tests: https://github.com/nextcloud/server/tree/master/tests -.. _Code Review Documentation: codereviews -.. _Drone: https://github.com/drone/drone -.. _Cucumber: http://cukes.info/ -.. _Transifex: https://www.transifex.com/nextcloud/ diff --git a/developer_manual/prologue/index.rst b/developer_manual/prologue/index.rst index 3b3253346..c065720a5 100644 --- a/developer_manual/prologue/index.rst +++ b/developer_manual/prologue/index.rst @@ -8,5 +8,4 @@ Prologue code-of-conduct help_communication bugtracker/index - development_process security