You want to invest your time into EXT:solr? That's awesome, because there are always things that you can do to help improve Apache Solr for TYPO3:
- Bug reports
- Feature requests
- Testing
- Documentation
- Support
- Translation
- Add-ons
In this guide we describe how you can contribute to EXT:solr, what are the guidelines and where you can get further information.
The source-code of EXT:solr is hosted on GitHub. The code is organized in branches
-
main: The main branch is the branch where the development for the latest TYPO3 version and the latest features is happening. It is our goal to keep this branch always working, but nevertheless it is a development branch. It is not recommended to use this branch in production.
-
release-X.X.x: Whenever major and minor releases are created from main we create a release branch. This is needed to allow providing bug fixes for older release branches.
If you want to help with development you should have the following things running locally:
- Some PHP environment - f.e. LAMP Stack - with TYPO3
- Apache Solr server with proposed version and configured schema & plugins - You can find a script included in the extension's "Resources" directory to help you to easily set up Solr and the required configuration
Please check the documentation for the required versions.
You can use the following preconfigured development environments to get started very quickly:
There is a ddev configuration with a preconfigured TYPO3 10 LTS and a local Solr server (version 8.5.1):
https://github.com/TYPO3-Solr/solr-ddev-site
To start the ddev follow its README.
You've found a bug or have an idea for a new feature or even better you've developed a new feature and want to share it? That's Great!
In EXT:solr we organize the tasks that we are working on using GitHub issues.
The first step should be to create a new issue or start a discussion in our Slack channel.
In case of a bug report it is essential for us to know as much as possible about how to reproduce the issue in order to quickly fix it.
The following information is useful:
- TYPO3 version
- Solr version
- PHP version
- Error messages / stack traces
- Expected behavior
- Actual behavior
- Steps how to reproduce the issue
In an ideal case you create a pull request and in the perfect case your pull request already contains a regression test that demonstrates the issue and prevents us from having the same issue again.
When you create a pull request, the message should
- Contain a meaningful title prefixed with the type of task ([BUGFIX] / [TASK] / [FEATURE])
- Contain a description with ** What was changed ** A relation to the issue the PR fixes by adding "Fixes #"
You may also want to read the following: https://github.com/blog/1943-how-to-write-the-perfect-pull-request
It is good practice if your pull request is as atomic as possible. Keep each commit small and focus on one change. This way it is easier to follow your changes during review.
Before you create a branch for new changes you should update your fork with the latest changes from our main.
To do this you need to do the following steps:
- Checkout your main branch
- Make sure our repository is configured as upstream (You only need to do this once)
- Rebase your main onto the upstream repository's changes
- Push the changes to your main
git checkout main
git remote add upstream https://github.com/TYPO3-Solr/ext-solr.git
git pull --rebase upstream main
git push --force origin mainIn the beginning it seems hard but after some time it's really handy to follow this example of how to prepare a pull request from your local branch.
Before you start, create your own fork on GitHub and follow these steps:
git clone https://github.com/YourGitHubAccount/ext-solr.git
git checkout main
git remote add upstream https://github.com/TYPO3-Solr/ext-solr.git
git checkout -b 'bugfix/4711-my-bugifx'
# Now do your coding and testing
git commit -m "initial commit"
# Now you do some implementation and testing and commit you improvements
git commit -m "do some cleanup"
# Check the log and rebase
git log
commit 0ee764f44de07ea97b19ad8272f60f3011bbf52b
Author: Timo Schmidt <[email protected]>
Date: Thu Jan 14 10:17:04 2016 +0100
Fixed wording
commit 1b8ba76ac15263876d71088ffc05983b40919919
Author: Timo Schmidt <[email protected]>
Date: Thu Jan 14 10:16:20 2016 +0100
First implementation
commit 1ea657dfed4d41a4e457a15520d4e95efba4a4c3
Author: Ingo Renner <[email protected]>
Date: Thu Jan 7 22:12:37 2016 -0800
Last commit from main
Change-Id: I17905b641ef322da09d2b93ed8adbd279ec680f0
# Git rebase
git rebase -i I17905b641ef322da09d2b93ed8adbd279ec680f0
pick 1b8ba76 First implementation
s 0ee764f Fixed wording
# Rebase 1ea657d..0ee764f onto 1ea657d (2 command(s))
# ...
# Note that empty commits are commented out
# Push it to a remote branch of your fork
git push origin 'bugfix/4711-my-bugifx'This was just an example, you can also push and rebase afterwards but digging more into git would be a topic on its own.
To get a change merged you need to:
* Create a pull request on GitHub, with a green build status.
* Somebody else needs to test it and give a +1 before the feature can be merged.
Our goal is to deliver working software, with as few bugs as possible and on the other hand have the possibility to implement new features quickly. To make this possible we have some conventions and use a set of tools that support us.
All files use the PSR-2 coding standard. The coding standard is automatically checked and enforced for every pull request by our continuous integration scripts.
If you want to check the code-style locally before you commit or just automatically want to fix it there is a great tool:
composer install
./.Build/bin/php-cs-fixer fix -v --level=psr2 --dry-run ClassesWhen you remove the --dry-run flag php-cs-fixer also fixes all violations.
Since version 3.1 we've switched to namespaces and use the "PSR-4" standard for class loading. In a nutshell this means:
- All classes in the "Classes" folder have the root namespace
ApacheSolrForTypo3\Solr - The namespace below
ApacheSolrForTypo3\Solrrepresents the directory structure and should be in upper camel case. - Make sure that the casing matches since most server operating file systems are case sensitive.
Changes should at least be tested manually to make sure the extension is still working and no new problems are being introduced.
To speed up the development process and allow major refactoring and improvements in a reasonable time we want to improve our set of automated tests. This also helps us to continuously integrate EXT:solr with the latest state of TYPO3 CMS development.
In "Tests/Unit" you can find unit tests for some classes. It is our goal and it is highly appreciated if you add tests for your code or contribute tests for existing code.
To test the integration between different classes and components you can add integration tests that cover these components. In our test setup we currently do the following:
- We use the TYPO3 Core functionality for "Functional" tests that sets up a dedicated test database and can be used in the integration test.
- We use our install script to set up a local Solr server on the test system. By doing this, we can do "end-to-end" tests and check whether the whole "stack" is working.
The simplest way to use the testing framework is to just enable Travis CI for your fork and automatically have Travis execute the tests for you. If you want to run the tests on your local system you need to follow these steps:
One time preparation:
cd <solrroot>
chmod u+x ./Build/Test/*.sh
./Build/Test/cleanup.sh
source ./Build/Test/bootstrap.sh --localEach time you want to run the test suite:
./Build/Test/cibuild.shMake sure that the test suite is running, before you do a pull request.
As alternative for a local run you can use our Docker test setup to run the tests
cd ./Docker/Ci
make bootstrapand afterwards:
make testNote: We will drop the support of our Docker test setup in upcoming versions in favor of our ddev setup DDEV Apache Solr for TYPO3 System.
The documentation for typo3-solr exists in the Documentation subdirectory.
It is rendered on docs.typo3.org:
It can be modified by changing the reStructuredText files (.rst).
The documentation for this extension has the same structure as the official TYPO3 documentation and is generated using the same workflow, tools and infrastructure as the official TYPO3 documentation.
Please look at the general information about TYPO3 documentation for more information:
- Directory and file structure
- How to contribute
- reStructuredText & sphinx
- Render documentation with Docker
For issues and pull requests, please use the tag [DOCS] in your commit messages / PR title / issue title, e.g.:
[DOCS] Fix typos
Until version 3.1.x the translation was done in the old TYPO3 locallang XML format. These files are available on http://translation.typo3.org
We've migrated the translation files to the new Xliff format. They can be found in "Resources/Private/Language". We appreciate any help here and it would be nice, if you could share your translations to complete the defaults here.
EXT:solr provides a set of hooks to extend it or use objects from EXT:solr in your own extension and build your custom functionality. On https://github.com/TYPO3-Solr/ we provide a couple add-ons to use with EXT:solr.
If you want to share your own add-on and would like to make it available within the Apache Solr for TYPO3 GitHub organization please don't hesitate to contact us!
The main support channel is our Slack channel. You can get support there from other community members and also support other users with the issues they might have.
You can support further development by becoming a partner. Check http://www.typo3-solr.com or call dkd (+49(0)69-24752180).