TYPO3 Contribution Guide - Core Development:Guide for contributing to TYPO3 core.
Home Page: https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/
On these pages you will learn how to become a TYPO3 Core contributor.
| Repository: | https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-ContributionWorkflow |
|---|---|
| Read online: | https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/ |
Create a cheatsheet which puts all the basic (git) commands on 1 page.
https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Account/GerritAccount.html
In general: Name and structure the chapters as to what the person wants to do next. Focus on task, not tool. Use terminology that is common practices in contribution guides.
Following things belong together and might be restructured:
setup
Submitting a patch
restructure and rename some things in the appendix
From Slack: There was a problem with setting up the commit hooks with composer
composer run gerrit:setup
Class TYPO3\CMS\Composer\Scripts\InstallerScripts is not autoloadable, can not call gerrit:setup:commitMessageHook:enable script
Class TYPO3\CMS\Composer\Scripts\InstallerScripts is not autoloadable, can not call gerrit:setup:preCommitHook:enable script
Should we still list the copy commands (as before)?
At top of existing section, https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/HandlingAPatch/Review.html, add best practices / most important points at top.
like on https://docs.typo3.org/:
I don't know if this is really necessary, but I saw that bamboo runs it and it is pretty easily done to execute it locally, and make sure the code is ready for a higher level.
Currently level 2 is used, which is not very high.
./bin/phpstan analyse --no-progress --no-interaction
./bin/phpstan analyse --no-progress --no-interaction -l3
Information about deprecation is in: https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/Appendix/HowToDeprecateThings.html
There are some things missing:
There is a complete new chapter Core Testing in "TYPO3 Explained", together with quickstart, examples etc. so this chapter here is no longer required.
Should this be merged?
https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Appendix/HowToDeprecateThings.html
Example from core:
// @deprecated since TYPO3 v9, will be removed in TYPO3 v10. Remove along with database field data_page_reg1
Found this really helpful https://forge.typo3.org/issues/91357#note-4 and desided therefore to add a PR for this. Since I'm new to git bisect it will be more initial proposal.
The section on commit message rules is very long: https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Appendix/GeneralTopics/CommitMessage.html
It might be useful to
Maybe I am missing something important, but I have issues following the guide https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-ContributionWorkflow/blob/master/Documentation/Testing/Index.rst
It should be noted IMHO that the steps from https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Setup/SetupTypo3.html?highlight=yarn are necessary first.
The docker image ‹typo3gmbh/php72:latest› has no file /sbin/my_init - so the commands under "docker run" give an error about it.
There is also no ‹bin/chromedriver› in the docker image.
Probably I missed something. Maybe I am using it wrong. I wanted to run the core tests locally.
Could be added somewhere on this page: https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/BugfixingAZ/Index.html#
Typical problems:
cherry pick:
peters@t3coredev$ git fetch https://review.typo3.org/Packages/TYPO3.CMS refs/changes/70/56470/8 && git cherry-pick FETCH_HEAD
From https://review.typo3.org/Packages/TYPO3.CMS
* branch refs/changes/70/56470/8 -> FETCH_HEAD
error: could not apply e1fe3c7cff... [BUGFIX] Change datatype of hash fields in index_words table
hint: after resolving the conflicts, mark the corrected paths
hint: with 'git add <paths>' or 'git rm <paths>'
hint: and commit the result with 'git commit'
The guide is mostly targeted for developers but the section on "Reporting a Bug" etc. would be really useful for people reporting bugs.
Not much needs to be changed here, most of the text is generic.
For the parts that are specific we could add extra sections for developers + non-devs. (issue reporters).
Sample text snippets:
P.S. I am already working on a PR for this.
How to setup a running TYPO3 installation is missing in this guide.
Could be placed in the new chapter Setup/SetupTypo3.rst
While this is probably something that everyone knows how to do who is advanced enough to contribute to TYPO3, it might be good to provide a quick overview and and least one recommended procedure with basic steps (e.g. docker, TYPO3 homestead, ddev ...).
When moving please make sure to always:
{{delete}} and {{outdated}}Later (or where it is a no-brainer and it is certain it can be deleted, this can be done right away):
see for information about migrating: https://wiki.typo3.org/WikiMigration
Important: Some of the pages in the Wiki still contain useful information that is not yet documented in the Contribution Guide. Do not just delete the Wiki pages! Read them carefully and check if there is still text that is worth saving and migrating to the current contribution guide on docs.typo3.org!
Not sure where this could go, but it might point out that new contributors are welcome, include some tips for new contributors and pointers to issues that are easily solvable, e.g.
Should be checked with core team first ...
After adding the index, some of the links (created with :ref:) no longer contain the title of the section as the anchor text. They now contain the section labels. 😦
Some things need to be done once only once per
It might be a good idea to go through the manual and group these steps very clearly into subsections.
P.S. I haven't really thought this through and checked it myself, just something to keep in mind and review the manual accordingly.
new: https://my.typo3.org/index.php?id=2
More information: https://my.typo3.org/index.php?id=33
Update following sections:
I had a case today, that a user using ubuntu 18.04 tried to follow the guide
https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/Appendix/SettingUpTypo3Ddev.html on a fresh machine (no yarn installed yet).
and failed on the yarn install because ubuntu suggests wrong way of installing yarn.
$ cd Build
$ yarn install
Command 'yarn' not found, but can be installed with:
sudo apt install cmdtest
$ sudo apt install cmdtest
$yarn install
00h00m00s 0/0: : ERROR: [Errno 2] No such file or directory: 'install'
$yarn build
00h00m00s 0/0: : ERROR: [Errno 2] No such file or directory: 'build'
According to https://stackoverflow.com/questions/46013544/yarn-install-command-error-no-such-file-or-directory-install
using cmdtest package suggested by ubuntu is not correct, but yarn should be installed using npm.
Also, is this really good to have it in Setup? Setting up the commit message template is setup, the rest is not. Maybe should be moved to "Fixing a bug"?
We could use Include commit-message.txt in 2 places, but I think it is better to not have duplicates at all.
P.S. Please wait for my pending PR which I will upload in a couple of days / 2 weeks. This will probably take care of most of the still pending issues.
A section about the JavaScript / TypeScript setup is missing - should also contain information about how to run the tests / build.
todos:
Should include:
P.S. I am already working on a PR for this.
The logger chapter starts with a subchapter "quickstart" which walks you through the most basic stuff. After that the more detailed information follows.
I think this would be a good idea for the contribution guide. Most contribution guides of other projects are:
While our guide is better in some ways because you can jump directly to a section via the menu and search, it might be a good idea to have a basic 1-2-3 step walkthrough for fast learners or people who know the basic stuff but just need to look up a command.
The tool can make it easier to use Gerrit. Test the tool and possibly document it. (install with pip is possible)
https://www.mediawiki.org/wiki/Gerrit/git-review
e.g. Ubuntu
apt-get install git-review
In local TYPO3 git working directory:
git review -s
Could not connect to gerrit.
Enter your gerrit username: speters
Trying again with ssh://[email protected]:29418/Packages/TYPO3.CMS
Enter passphrase for key '/home/sybille/.ssh/id_rsa':
Creating a git remote called 'gerrit' that maps to:
ssh://[email protected]:29418/Packages/TYPO3.CMS
This repository is now set up for use with git-review. You can set the
default username for future repositories with:
git config --global --add gitreview.username "speters"
As suggested by git review :
git config --global --add gitreview.username "speters"
cherry-pick change 57131
git review -x 57131
In the Contribution Guide there is a chapter “Setting up your frontend build toolchain” that assume an already installed source that is described at a later point.
Maybe split the chapter “Prerequisites and useful tools” into “Prerequisites” and “Useful tools” and then put “Setting up your Git environment” between “Prerequisites” and “Useful tools”.
There is a video showing installation with DDEV.
https://www.youtube.com/watch?v=HZVMPoI9SIk
It would be very nice to have the video incorporated in this page:
https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/Appendix/SettingUpTypo3Ddev.html
Currently, there is some overlap of information, specifically in:
This information could be merged into one chapter and duplicate information removed.
Additionally, the page on Gerrit might be changed to be more consistent with the rest of the guide, specifically:
The page Creating a patch (formerly: "Fixing a bug") has grown over time and is now pretty long. It contains a number of steps and extra information that don't necessarily always need be performed (e.g. changing a patch with git commit --amend or adding to the changelog) or that were already explained elsewhere (e.g. coding guidelines). The use of sections and subsections makes it hard to sort out (at first glance when browsing the page) what is a section and what is a separate step in a section.
Suggestion: Do one or more of the following
In order to make it easier for the reader, find and document some best practices for writing in this guide: https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Appendix/ResourcesForEditors/Index.html or move that section to CONTRIBUTING.md on GitHub.
Creating FIRST_INSTALL is probably not necessary. Check to see if the database exists. ddev describe should give you enough information for that.
Should really get fixed. Either it is necessary or not.
yarn is mentioned in several places. Add cross-references linking to section for installing and building:
Add links on pages:
Related:
e.g.
git pull --rebase origin master)Should preferably be added to advanced section on changing patches etc. This is currently found in "Lifecycle of a patch" in the Appendix, and should possibly be moved to the main section after "Writing a patch". (as adressed in PR #97)
see also https://typo3.slack.com/archives/C03AM9R17/p1538571897000100
https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/ReportingAnIssue/Index.html
Is a bit long. Perhaps we should reduce it to the main points people are usually struggling with. For me that has been (among others):
In that case it might be grouped more like an FAQ and the general (short) description separate.
There are various resources and examples for templates in projects.
Following could be included:
Start, once repo on GitHub has been renamed (should be July 19, 2021) ,,,
Before
The basic flow used to look like this:
git clone git://git.typo3.org/Packages/TYPO3.CMS.git .
git config url."ssh://<YOUR_TYPO3_USERNAME>@review.typo3.org:29418".pushInsteadOf git://git.typo3.org
git config remote.origin.push +refs/heads/master:refs/for/master
After
The recommended—new—way of doing this is:
git clone git://github.com/typo3/typo3 .
git config remote.origin.pushurl "ssh://<username>@review.typo3.org:29418/Packages/TYPO3.CMS.git"
git config remote.origin.push +refs/heads/master:refs/for/master
https://typo3.org/article/renaming-the-typo3-github-repository
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.