diff --git a/Documentation/BugfixingAZ/Index.rst b/Documentation/BugfixingAZ/Index.rst index 192470e9..6841b55f 100644 --- a/Documentation/BugfixingAZ/Index.rst +++ b/Documentation/BugfixingAZ/Index.rst @@ -80,6 +80,10 @@ as described in :ref:`setup `. Especially the See :ref:`Testing the core ` in TYPO3 Explained for more information about writing and running tests. + Once you have finalized your patch, check out the :ref:`common-review-checks` + for a list of what kind of review checks people may perform on your contribution. + Stay ahead of the game and address those yourself first. + #. Commit your changes Please make sure that you read the :ref:`commitmessage` in the Appendix. @@ -167,9 +171,10 @@ as described in :ref:`setup `. Especially the You can visit the link to https://review.typo3.org to see your patch in Gerrit. - If the automatically starting pre-merge build fails due to an error on Bamboo which - isn't caused by your patch (e.g. time out) you can restart it on - `Intercept `__. + The Continuous Integration service, running on GitLab Pipelines, will automatically + be executed in the background and perform checks and tests on your patch. + Failing tests will be linked to that instance, where jobs can also be retried + (given sufficient permissions when being logged in to GitLab). Advanced users / core team only: See :ref:`cheat sheet: other branches ` @@ -193,6 +198,9 @@ dozens of requests each day, so expect a succinct response that is short and to You will get notified by email, if there is activity on your patch in Gerrit (e.g. votes, comments, new patchsets, merge etc.). +Check out the section :ref:`reviewPatch` for more about this process, in which you can +also be involved! + It is not unusual for a patch to get comments requesting changes. If that happens, please respond in a timely fashion and improve your review. If things are unclear, ask in the **#typo3-cms-coredev** channel on https://typo3.slack.com. diff --git a/Documentation/CoreMergers/Review.rst b/Documentation/CoreMergers/Review.rst index b669c698..a254c565 100644 --- a/Documentation/CoreMergers/Review.rst +++ b/Documentation/CoreMergers/Review.rst @@ -13,7 +13,16 @@ Review a patch as a Core Merger .. include:: /_includes/CoreMergers.rst.txt Please see :ref:`reviewPatch` for general information on how to review a -patch. +patch, also the :ref:`cheat-sheet on common review issues `. + +As a Core Merger you have a huge responsibility because your vote (or misvote) +has an impact on dedicated work of contributors or colleagues. This swings +both ways: You can also greatly impact confidence and participation by being +involved in a public voting and commenting process. + +Remember that you represent the TYPO3 project as a public-facing "Person with Power". +Please try to always vote by explaining your reasoning, and feel free to +correspond with your fellow Co-Mergers for impactful decisions. .. figure:: /Images/External/Gerrit/CoreMergers/VoteCoreMerger.png :class: with-shadow @@ -69,7 +78,8 @@ Low brainers ------------- A Core Merger can give a +2 and submit right away in case of "low-brainers" -(what used to be called "FYI"). +(what used to be called "FYI" and relates to changes that are highly +unlikely to negatively impact anything). A Core Merger can give a +2 and wait a bit before submitting (used to be called "FYI24", "FYI48", ...). diff --git a/Documentation/HandlingAPatch/ChangeAPatch.rst b/Documentation/HandlingAPatch/ChangeAPatch.rst index 3a9c8a38..4b975943 100644 --- a/Documentation/HandlingAPatch/ChangeAPatch.rst +++ b/Documentation/HandlingAPatch/ChangeAPatch.rst @@ -36,7 +36,9 @@ This chapter handles improving an existing patch. For creating a new patch, see 4. Test your changes (optional) - Run the TYPO3 testsuite locally, as described under :ref:`testing`. + Run the TYPO3 testsuite locally, as described under :ref:`testing`. Otherwise, + don't worry, the automatic CI will do that for every committed patch set on the + TYPO3 infrastructure. 5. Add files and amend to commit @@ -54,6 +56,12 @@ This chapter handles improving an existing patch. For creating a new patch, see You can amend as often as you want. + Bear in mind that this kind of Git commit amending is a bit different than + when you do it with GitHub (and using `force-push`). For Gerrit, every push + will be a patch set. Previous patch sets can never be overwritten by amending, + so do not worry. + +.. _git-commit-with-message: 6. Push your change to Gerrit Once you are satisfied, push your improved Patch Set to Gerrit: @@ -62,3 +70,27 @@ This chapter handles improving an existing patch. For creating a new patch, see :caption: shell command git push origin HEAD:refs/for/main + + Each pushed set will iterate a new patch set, and all previous patch sets + can always be compared and even checked out later on. + + If you want, you can even provide an individual commit message to your push, + so that in gerrit your code change shows up with what usually a + "commit message subject" could do: + + .. code-block:: bash + :caption: shell command + + git push origin HEAD:refs/for/main%m="Some_String_Without_Whitespace" + + The underscore characters will be replaced by whitespace. You can also + use the following bash script or shell alias to interactively do that: + + .. code-block:: bash + :caption: push-with-message.sh + + #!/bin/bash + + read -p "Please enter pseudo-commit message: " answer + answer=$(echo "$answer" | tr -c '[:alnum:]' '_') + git push origin HEAD:refs/for/main%m=$answer diff --git a/Documentation/HandlingAPatch/FindAReview.rst b/Documentation/HandlingAPatch/FindAReview.rst index 73f8f236..19528660 100644 --- a/Documentation/HandlingAPatch/FindAReview.rst +++ b/Documentation/HandlingAPatch/FindAReview.rst @@ -91,6 +91,29 @@ Gerrit: Search Or use the search box on `Gerrit `__ +GitHub: Links to Gerrit +======================= + +Each commit to the TYPO3 Git repository comes with some metadata +linking issue and patch reviews, for example: + +.. code-block:: + + [TASK] Provide PSR-7 Request in PolicyMutatedEvent + For additional context does the PolicyMutatedEvent + now provide the current PSR-7 Request. + + Resolves: #104141 + Releases: main, 12.4 + Change-Id: I1817366e77f20f6c43eef0ee209fbb419e7237e2 + Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/84913 + Tested-by: Lorem Ipsum + Reviewed-by: Lorem Ipsum + Tested-by: core-ci + +The line `Resolves` contains the Forge issue id. +The line `Reviewed-on` contains the link to the gerrit patch. + Forge ===== diff --git a/Documentation/HandlingAPatch/ResolveMergeConflicts.rst b/Documentation/HandlingAPatch/ResolveMergeConflicts.rst index 22aec4e5..b1466baa 100644 --- a/Documentation/HandlingAPatch/ResolveMergeConflicts.rst +++ b/Documentation/HandlingAPatch/ResolveMergeConflicts.rst @@ -201,10 +201,11 @@ However, git status will show you: All files shown with "both modified" will need to be attended to. -Resolve the conflicts ---------------------- +Resolve the conflicts manually +------------------------------ -If you want to do it manually, look for all occurrences of `<<<<<<<`. +If you want to do it manually (instead of using an IDE to do it visually), look for +all occurrences of `<<<<<<<`. These are markers. They are used as follows (as in example above): @@ -229,6 +230,33 @@ The merge conflict will show: There may be more than one conflict in a file! +Special case: JavaScript/CSS merge conflicts +-------------------------------------------- + +JavaScript and CSS assets are build from sources in the monorepo, with the commands: + +.. code-block:: bash + + Buid/Scripts/runTests.sh -s buildCss + Buid/Scripts/runTests.sh -s buildJavascript + +This "compiles" files with ".scss" and ".ts" extensions to their bundled ".css" and +".js" variants. TYPO3 also versions these files inside the monorepo. + +Commiters need to be aware they need to maintain these asset versions, if they change +any of the build source files, and commit them alongside their patch. + +Since the compiled files are merged on one single line, a merge conflict in these files +will occur, if your patch works on anything CSS/JS related and other changes +have been introduced meanwhile. + +The solution to resolve merge conflicts in these files is actually vers easy. Just +re-perform the commands from above (`...buildCss/buildJavascript`), which will re-create +the assets from your cherry-picked patchset. You may need to resolve conflicts in the +`.ts/.scss` files beforehand, if there are any due to rebasing. + +Afterwards, you can include the generated `.css/.js` file your git amend commit like +any other resolved conflict (see below). Resume command -------------- @@ -257,3 +285,14 @@ Resume git cherry-pick .. code-block:: bash git cherry-pick --continue + +Commit changes after rebase/cherry-pick +--------------------------------------- + +Once your git repository is in sync with `HEAD` and your cherry-picking was +successsful, you can edit/add files, commit and push as usual: + +.. code-block:: bash + + git commit --amend + git push diff --git a/Documentation/HandlingAPatch/Review.rst b/Documentation/HandlingAPatch/Review.rst index d3674e74..fb39d354 100644 --- a/Documentation/HandlingAPatch/Review.rst +++ b/Documentation/HandlingAPatch/Review.rst @@ -13,6 +13,9 @@ Reviewing a patch consists of two steps: You have the option to contribute to both stages or just a single stage in the review process. +Both steps are free for everyone in the OpenSource community, you are not required to be +a Core merger or Team member. + If you're able to improve the patch yourself, your contribution would be very much appreciated. Visit :ref:`lifeOfAPatch-improve-patch` to find out more about how you can help improve patches. @@ -35,6 +38,8 @@ Code Review A basic code review is possible by using the Gerrit web interface. +For some tips on what to review, check our :ref:`common-review-checks`. + .. rst-class:: bignums-xxl #. Select the latest patchset @@ -127,6 +132,9 @@ Vote In order to comment or vote on a change you can click on the :guilabel:`Reply` and enter your comment. Here, you can also apply your votes. +Remember, everyone with just a TYPO3 user account is able to vote, you do not +need to be a team member or Core merger. + .. figure:: /Images/External/Gerrit/CoreMergers/VoteUser.png :class: with-shadow @@ -158,9 +166,11 @@ Policy for votes **Verified:** Needs :guilabel:`+1` of two reviewers, one of them being a Core Merger. -Votes from the Bamboo build server (user *TYPO3com*) do not count. This means +Votes from the CI GitLab Pipeline Server (user "Core CI") do not count. This means that a patch which is fully reviewed usually has at least 3 **Verified** :guilabel:`+1` -votes, two from humans and one from Bamboo. +votes, two from humans and one from "Core CI" ("Core CI is happy" for Verified+1, "Core CI is not happy" +for Verified-1). Each comment by Core CI is linked to the log of the performed job, +so that you can inspect the output. **Authors should not vote for their own patches**, unless the patch has been changed substantially by other developers. @@ -194,7 +204,26 @@ be solved until this or that is fixed". Some hints on using -1 in reviews: a deeper knowledge of this subsystem, to take a look at it. I do not want this patch to be merged until this is sorted out and will vote -1 for now for this reason." +* If you are on the "receiving end" of a "-1" or even a "-2" vote, please do not + be afraid or feel bad. This is done as part of the process to make TYPO3 + evolve as best as it can. Try to work out problems or negative feedback, + be kind to each other and remember you are contributing to OpenSource because + the experience of improving things together, and learning from each other + is what drives us. + +Vote resets ("Revote") +---------------------- + +Whenever a new patch is submitted, all votes are reset. So if previously +a patch was voted to be merged, but then a last-minute issue is getting +addressed, after the commit every vote will be back to zero. +Contributors to a patch review will receive notifications about this and +are encouraged to review the patch and re-apply their vote if they +still feel confident. + +It is ok if the patch owner pings previous votes to please consider +adding a revote, so that a patch can be pushed forwards. How to handle [WIP] patches =========================== @@ -222,3 +251,24 @@ following this solution to its end." Having too many WIP patches in the review queue is not really helpful. Consider to fork the project in GitHub or somewhere else and push to gerrit again if your patches evolved. + +Stale reviews / Cleaning up +=========================== + +Since TYPO3 iterates on many, many patches and issues each day, the list +of Gerrit reviews (as well as Forge issues) may feel intimidating. + +Due to this it is vital to "clean up" patches from time to time: + +* If you are no longer planning to work on a patch, maybe better anbandon + it, or ask other involved people to carry on. +* If your patch is not getting feedback for a long time, ask in the + #typo3-cms-coredev channel of the `TYPO3 slack workspace `__ + if people may want to review or give feedback on. Or try to find people + working in a similar area of your patch and see if you can join forces. +* From time to time, check on patches you have voted on, to see if you can + push things forward to either get merged or abandoned. +* Sometimes just check all your own open patches and see if you might catch + interest in picking it up again. +* Please either update older patches in "Merge conflict" mode or state your + intent to abandon the patch. \ No newline at end of file diff --git a/Documentation/HandlingAPatch/Tips.rst b/Documentation/HandlingAPatch/Tips.rst index 6ba3e0ab..0eca0393 100644 --- a/Documentation/HandlingAPatch/Tips.rst +++ b/Documentation/HandlingAPatch/Tips.rst @@ -274,4 +274,44 @@ Voting Consider the :ref:`policies and tips for voting patches `. +.. _common-review-checks: + +Common code review checks +------------------------- + +For reviewing and giving feedback, here's a couple of things that are often addressed. You can +use this list both for checking other people's patches, as well as your own. + +* Is the code-flow readable? Does it need more (or less) comments? Any code complexities + ("cognitive complexity") that could be easier to read when using different conditions/loops/sub-methods? +* Do breaking changes occur that need to be noticed? This can also apply to: + * Type Hinting + * using PHP features beyond the supported PHP version + * Loss of existing functionality + * Typos +* Are new class, method, function, variable names understandable +* Is there a need to add unit/functional testing for specific changes +* Are regression tests for a bugfix needed? +* Is the "Releases: " scope of a patch spanning the proper TYPO3 versions + (depending on the state of current LTS and priority-bugfix-only releases) +* Are the "final" and "private/protected" and "readonly" scopes of classes, methods and variables used properly? +* Is Dependency Injection used where applicable? +* Are possibilities for early code returns and reduced nesting levels addressed? +* If a change is Breaking or comes with a larger impact: Is a "Breaking.rst" or "Important.rst" document part of the patch? +* If a patch is a new feature: Is a "Feature"-rst part of the patch? Check out the `rst file generator ` + for help on creating files like this. +* Does the licensing of any foreign code introduced match the Core licensing? +* Is the commit message complete, clear and properly mentions all part of a patch? +* If a new Exception is added, is the timestamp-identifier unique and recent? +* When new PHP files are added, do they contain the TYPO3 License and a `declare strict_types` header? +* Is the provided commit message, reST files and the code itself aligned? Sometimes in the process + of reworking a patch multiple times, these three place of documentation can become out of sync. +* If SCSS/TS changes are involved, are the resulting build files included in the patch, and were built with the + right environment? +* Does your patch deprecate anything? If so, have you followed :ref:`deprecations`? + +If you feel this section is missing good things to watch out for for, please contribute to the +documentation. This list does not claim to be complete, but should act as a kind of "Cheat-Sheet" for +reviewing. + diff --git a/Documentation/HandlingIssues/TicketWorkflow.rst b/Documentation/HandlingIssues/TicketWorkflow.rst index 04026d9e..607e7645 100644 --- a/Documentation/HandlingIssues/TicketWorkflow.rst +++ b/Documentation/HandlingIssues/TicketWorkflow.rst @@ -12,17 +12,170 @@ Issue Workflow (Forge) ====================== -This chapter describes the workflow of handling issues in TYPO3s Redmine -available at Forge_. Once issues have been submitted, there may be information -missing or the status may changed. Additional information can be added. +So, you've filed an issue following the steps above, and submitted it. -Everyone is welcome to help in improving issues. +What now? + +First and foremost: Thank you for doing this. You are now a part of the OpenSource +ecosystem. It lives and thrives with its users, and is constantly evolving. + +The TYPO3 community is proud to be active and diverse, and boast a long-standing +track record of fostering this system that we all love with continuous development +effort. + +Most of the TYPO3 Contributors perform their work in their spare time, and we all +spend our time differently. Some people work on big tasks and have an agenda of +years ahead, and maybe are even paid to work on TYPO3 (through either Partners, Agencies, +TYPO3 GmbH or other means). Other people work on this system instead of watching a +movie in the evening. + +So the bottom line is: In OpenSource development, you do not really know who and when +somebody will take care of your issue. It can catch someones instant attention, +but it may also lay unchecked for days, or weeks... or longer. Impactful bugs are +easily addressed because the more people report an issue, the more likely it is to +get awareness and interest. + +A few volunteers in the TYPO3 community try to regularly catch up with issues, +so no report is likely to be lost like tears in the rain. Your input is valuable, +and valued by our team - but please bear with us. + +If your issue does not get addressed immediately, try to get involved in the Community. +Check out `https://typo3.org/help`__ for platforms to discuss about the issue you found. + +Or, maybe you can find time and capacity to work on an issue yourself, with the help of this +Contributor's Guide! + +Once an issue has been triaged by our support volunteers, this will usually happen: + +.. index:: + single: Issue Workflow; Status + +Status +====== + +#. New + + This is the initial state of an issue. It may get reverted to this status, + when possible feedback loops are done, but the issue itself could not yet + be "Accepted" due to missing strategic or capacity decisions. + +#. No status change, but "things happen" + + Your issue may remain in status "New" or "Accepted", but further feedback + might be added, or relations to other issues could be added, or + other metadata (like tags) get adjusted. If you see this happening, + some of our support staff has "seen" your issue. If your issue is + older, and you see this happening, this might be a good time to get + involved again and see if your issue still applies. + +#. Needs Feedback: + + Your issue has been set from Status "New" to "Needs Feedback". + + This means, we have further questions to process or discuss your issue. + Once you provide the feedback, the person involved with it will usually + get back to you again. + +#. Accepted + + Your issue has been "accepted" to be reproducible and understandable, + and will hopefully find a volunteer to fix it. + + Please bear in mind that this status does not mean someone immediately + begins to work on it. It is just a status that developers can use to + search for accepted issues to work on. And it is a good pool of issues + to address for example in remote or on-site Code sprints (see + `https://typo3.org/community/meet/regular-open-sprints`__). + +#. In Progress + + Someone has actively taken on your issue to work on. + +#. Under Review + + This is the status you are looking for. + + This means a Patch has been made that should address your problem. + The link to such a Patch in our review system will be attached to the + comment. + + Now it is very important for that patch to: + + * actually fix your issue + * be accepted by Core mergers to be part of the TYPO3 code + + Anyone can create/contribute a patch to any issue, one does not need + to be assigned to it. One is also free to contribute to existing + Patches of an issue. + + And most importantly: You are VERY welcome to review the patch + yourself. If you can comment on the patch tracking system that + a patch solves your problem, and even vote for it, this will + highly increase the chances of your patch getting merged. + + Sometimes discussion about solving an issue is then carried on to the + Gerrit review system, which is linked in the issue comment. You may want + to regularly check on that patch state and maybe give feedback there. + + Please note that the patch system is meant for highly technical feedback. + If your feedback is more general, please provide that only in the issue tracker. + + An issue that is "Under Review" may get merged very quickly, but it may + also even take very long to get merged, or even rejected/abandoned. + +#. Resolved + + Making a note here: Huge success! Your issue report lead to an actual + code improvement of TYPO3, and the patch resulting from your issue + has been merged. Thank you! + + Sometimes it might not be what you expected at first, because requirements + and needs may change, and need to be adapted for the broad community. + + It can also occur that the issue you reported for a specific TYPO3 + version is only fixed for a more recent version, and not the one you + reported with. Sadly we cannot backport every single bugfix, and need + to make internal decissions about which changes get put into older + versions. Patches never get merged to versions below the LTS (Long-term support) + threshold. + + The upside: The patch that has been made may apply to your own instance. + You can always download patches and apply them locally, see + :ref:`Applying Core patches ` for details. + +#. Closed + + This may be a frustrating status for your issue to be put in. We need to + close issues that: + + * are no longer reproducible + * are outdated + * are not fixable/adressable within reasonable resource limits + * do not align with the TYPO3 project goal + * receive no feedback for a longer time + * relate to abandoned patches + + If your issue has been closed but you believe this is a mistake, our support + staff are just humans after all, please bear with us. You can still give feedback + to closed issues, you can reach out through other community means, or you can + also create follow-up issues. + +#. Outside help / Volunteering opportunity + + The more watchers an issue has, the more likely it is regarded as being of importance. + + It can help if you regularly search the issue tracker yourself for similar problems + than yours, and maybe set relations to new issues, or comment in issues that you + haven't submitted yourself, but where you can contribute. + + The task of maintaining the issue tracker is a large one; several dozen issues + are worked on each day. If you can help to add relations to related tickets, + or provide feedback or additional information in "foreign" tickets, this can help us out. + + The ideal help of course is if you are able to solve issues by providing solutions + or patches to issues. -There are edge cases to this which should be discussed on a per-case basis -in order to refine the workflow more. -If in doubt, ask on `Slack `__ -in the **#typo3-cms-coredev** channel. (Remember to :ref:`register ` first.) .. index:: @@ -56,28 +209,3 @@ time of release. Other members of the core team should support this cause by rev Features and tasks will go into this pool. These can be worked on as usual. - - -.. index:: - single: Issue Workflow; Status - -Status -====== - -When an issue is reported, the status is set to **New**. Here we list some -common status changes: - -**Needs Feedback** - -This issue needs more information to get resolved. It is good practice to always -combine this status change with a question to the issue reporter in order to -make clear, what kind of information is missing. - -**Under Review (Automatic)** - -As soon as a patch is uploaded for the issue, the status will automatically -be set to "Under Review". - -**Resolved (Automatic)** - -As soon as the patch is merged, the status will automatically be set to "Resolved". diff --git a/Documentation/ReportingAnIssue/Index.rst b/Documentation/ReportingAnIssue/Index.rst index 60a61fa9..3b25552b 100644 --- a/Documentation/ReportingAnIssue/Index.rst +++ b/Documentation/ReportingAnIssue/Index.rst @@ -80,11 +80,24 @@ Be up to date Or even better: use the latest version from git. +Be explicit + It can take a lot of time to reproduce or understand issues. Please try to + be as brief as possible, but as detailed as needed. Supplying code examples + to reproduce an issue, or showing screenshots helps a lot! + +Remain involved + If we have questions about your issue, and need feedback from you, please ensure + you get notified to replies to your issue and try to respond. Often, further + details are needed. + Talk to the core team - When in doubt, don't hesitate to talk to us on `Slack `__ + If you are a developer yourself and are able to address an issue (no matter if + bug or feature) yourself, but need some guidance on how to approach it, + don't hesitate to talk to us on `Slack `__ in the **#typo3-cms-coredev** channel. (Remember to `register `__ - first.) + first.) This channel is not a support channel for end-users. Those needs + are covered by `https://typo3.org/help`__. @@ -193,6 +206,12 @@ Category Choose a category that fits your issue. +Core developers tend to identify with certain areas of TYPO3, which are +mirrored in the category system (usually by "Core extension" or area). + +The better you can classify your problem, the more likely it is that +a Core developer will spot your issue in "his area". + .. index:: @@ -205,8 +224,12 @@ TYPO3 version (for bugs only) -Choose the TYPO3 version, where the error occurs. +Choose the TYPO3 version, where the error occurs. Ideally try +to report an issue for the latest TYPO3 version where your issue +applies to. +Older TYPO3 versions outside of the LTS support range are less +likely to receive attention. .. index:: @@ -250,6 +273,13 @@ Some hints for files: .. image:: /Images/External/Forge/new-issue2.png :class: with-shadow +(optional) Related issues +------------------------- + +If your search already yielded related issues to your own, it would be very helpful, +if you can add a relation to those ticket numbers. You can also do that afterwards, +and our support staff may also sometimes relate your issues. + .. tip:: Use the "Preview" function at the bottom of the page to check if your @@ -295,6 +325,10 @@ A good bug report should contain all or any of these elements: This is a short easy-to-follow guide that allows us to understand how to trigger the bug following it. Using a numerated list of steps is just fine here; you can also add screenshots. + If possible, use TYPO3 Core extensions like :ref:`use-styleguide` to make + an issue reproducible. The easier our support helpers are able to follow + your instructions, the more likely it is we can also find the problematic + area in the TYPO3 code. #. Actual results @@ -315,6 +349,11 @@ Please consider that these guidelines are very generic. Not always all these par necessary, but having the necessary information could help a lot to reproduce and fix the bug. +This not only applies to bugs, but also feature requests. For feature requests, +state why a change is needed/helpful, what problems it solves. TYPO3 is a very modular +and highly configurable system - not every feature needs to be solved in the TYPO3 core, +but can be an extension (maybe yours!) instead. + .. tip:: Use redmine formatting to structure your bug report and make it more readable, for @@ -405,6 +444,13 @@ descriptive anchor text. * `Redmine Info: External links `__ +Continued workflow +================== + +So, you've filed an issue following the steps above, and submitted it. + +What now? Read further in :ref:`issue-workflow`. + Additional Resources ==================== diff --git a/Documentation/Setup/UseStyleguide.rst b/Documentation/Setup/UseStyleguide.rst index 75fef741..71af7c1d 100644 --- a/Documentation/Setup/UseStyleguide.rst +++ b/Documentation/Setup/UseStyleguide.rst @@ -9,11 +9,11 @@ Use EXT:styleguide ================== -It is recommended to use the styleguide extension to auto generate several +It is recommended to use the `styleguide`` extension to auto generate several example pages which can be used for testing the frontend and backend of TYPO3. -The typo3/cms-styleguide extension is part of the TYPO3 core repository. -It used mostly to showcase TCA / FormEngine features but has since evolved +The :t3src:`styleguide` extension is part of the TYPO3 Core repository. +It used to mostly to showcase TCA / FormEngine features but has since evolved to provide additional features. The styleguide extension can create pages within the TYPO3 site, specifically: @@ -24,6 +24,19 @@ The styleguide extension can create pages within the TYPO3 site, specifically: the styleguide extension and creates pages which can be viewed in the frontend. +Also, the styleguide presents you with examples of several backend UI elements +like notifications, tabs, accordions and more. + +The extension is very helpful for Core contributors and reviewers, because it +allows to test many TCA related configurations easily, without the need to +create custom extensions to reproduce problems. + +`EXT:styleguide` has been integrated to the TYPO3 Core monorepository with +version 13. On older TYPO3 versions you need to install the package for example +via TER or Packagist (using Composer). + +Go explore! + Setup ===== @@ -48,7 +61,8 @@ Setup 1. Activate the styleguide extension in the extension manager 2. Click on :guilabel:`?` in the top bar -3. Click on the :guilabel:`Styleguide` menu item +3. Click on the :guilabel:`Styleguide` menu item (older TYPO3 versions + present a custom module menu item) The Styleguide overview appears. diff --git a/Documentation/Troubleshooting/Index.rst b/Documentation/Troubleshooting/Index.rst index 87a7a198..7e8c03f8 100644 --- a/Documentation/Troubleshooting/Index.rst +++ b/Documentation/Troubleshooting/Index.rst @@ -250,39 +250,56 @@ A valid private key in OpenSSH format starts with the following lines: followed by about 25 lines of seemingly random signs. -Pushing old Patch Set again ---------------------------- +Pushing old Patch Set again (updating/rebasing) +----------------------------------------------- -You want to make an old patch set the current one. You cannot simply -checkout Patch Set 1 and push it again, as it is refused with a "no new changes" error message. +If you want to update an older patch set/version, so that it appears to be the +current one, you always need to get an updated commit hash. So you cannot just +checkout Patch Set 1 (or any other one) and perform a Git push. This would be +refused with a "no new changes" error message. -Amend the commit using: +So you need to amend the commit using: .. code-block:: bash git commit --amend -Even without modifying the Commit Message, it gets a new SHA. This commit can be pushed again. +and then, even without modifying the Commit Message, it gets a new SHA. This commit +can then be pushed again. Resolving Merge Conflicts in generated asset files -------------------------------------------------- -If you cherry pick a patch for review; you might encounter a merge conflict with a generated asset file: +If you cherry pick a patch for review, you might encounter a merge conflict with a generated asset file +(JavaScript or CSS build files): .. code-block:: none :caption: result Mergeconflict in typo3/sysext/backend/Resources/Public/Css/backend.css -To resolve the conflict, use the following workflow: +To resolve the conflict, do not try to resolve conflichts in a huge 1-line file, but instead +re-create the assets using the following workflow: .. code-block:: bash :caption: shell command - cd Build - npm run build - git add + # Perform re-build using the helper "runTests.sh" + + # Make sure dependencies are up to date + ./Build/Scripts/runTests.sh -s composerInstall + + # Clean possibly previously build files + ./Build/Scripts/runTests.sh -s clean + + # Execute the build + ./Build/Scripts/runTests.sh -s buildCss + ./Build/Scripts/runTests.sh -s buildJavascript + + # Now add all conflicting files as resolved: git add typo3/sysext/backend/Resources/Public/Css/backend.css + + # Continue the cherry-pick process git cherry-pick --continue You will see the Commit Message again and you can now save it. diff --git a/Documentation/WorkflowExplained/Index.rst b/Documentation/WorkflowExplained/Index.rst index d7a2efb8..e86cf868 100644 --- a/Documentation/WorkflowExplained/Index.rst +++ b/Documentation/WorkflowExplained/Index.rst @@ -45,9 +45,10 @@ We use a 6-eye principle to ensure proper quality assurance and Gerrit_ helps us #. From here, any contributor can review the change. #. Reviewing consists of two parts, the **Code Review** where a contributor checks if the code style is according to our coding guidelines or in general `makes sense` by reading and the **Verification** which means if the code does what it - is supposed to do (like fixing an issue) and checks whether the unit tests run through. -#. If a review has enough positive votes, an **active contributor** (aka member of the core team) is able to merge that review - into the existing codebase. The reason we need a member of the core team to finally merge the change is that we run a - "You break it, you fix it" policy, so the core team member that merged a change immediately becomes responsible for that - change in case the original author decides to no longer work on it. And he / she will be responsible for - backporting it to older TYPO3 versions. + is supposed to do (like fixing an issue) and checks whether the unit, functional and acceptance tests run through. +#. If a review has enough positive votes (at least two people voting verified+reviewed), an **active contributor** + (aka member of the Core team, called "Merger") is able to merge that review into the existing codebase. The reason + we need a member of the Core team to finally merge the change is that we run a "You break it, you fix it" policy. + So, the Core team member that merged a change immediately becomes responsible for that change in case the original + author decides to no longer work on it. And he / she will be responsible for backporting it to selected older TYPO3 + versions.