Both sides previous revisionPrevious revisionNext revision | Previous revision |
development:recommended_tools [2019/01/30 16:22] – [Editors / IDEs] demiankatz | development:recommended_tools [2023/10/20 12:02] (current) – [Style] demiankatz |
---|
====== Recommended Tools ====== | ====== Recommended Tools ====== |
| |
Developers are free to use whatever tools they prefer, but this page provides some suggestions that may help newcomers make the most of VuFind development. | Developers are free to use whatever tools they prefer, but this page provides some suggestions that may help newcomers make the most of VuFind® development. |
| |
===== Editors / IDEs ===== | ===== Editors / IDEs ===== |
===== Version Control ===== | ===== Version Control ===== |
| |
It is strongly recommended that you use some sort of version control software to keep track of revisions while programming. This provides a valuable safety net for reverting bad changes, remembering why particular adjustments were made, etc. In the case of [[development:recommended_tools:git|Git]], the tool used by VuFind, it also offers powerful collaboration and sharing capabilities. Whether you plan to work locally or share with the local community, [[development:recommended_tools:git|Git]] is a tool worth learning more about, as is the [[http://github.com|GitHub]] platform, which enhances Git's native sharing capabilities with web-based collaboration tools. | It is strongly recommended that you use some sort of version control software to keep track of revisions while programming. This provides a valuable safety net for reverting bad changes, remembering why particular adjustments were made, etc. In the case of [[development:recommended_tools:git|Git]], the tool used by VuFind®, it also offers powerful collaboration and sharing capabilities. Whether you plan to work locally or share with the local community, [[development:recommended_tools:git|Git]] is a tool worth learning more about, as is the [[http://github.com|GitHub]] platform, which enhances Git's native sharing capabilities with web-based collaboration tools. |
| |
===== Dependency Management ===== | ===== Dependency Management ===== |
| |
VuFind loads its external dependencies using [[development:recommended_tools:composer|Composer]]. An understanding of Composer is important when running VuFind from a source checkout or when adding new third-party libraries. | VuFind® loads its external dependencies using [[development:recommended_tools:composer|Composer]]. An understanding of Composer is important when running VuFind® from a source checkout or when adding new third-party libraries. |
| |
===== Grunt ===== | ===== NPM Scripts / Grunt ===== |
| |
VuFind, as of version 3.1, ships with a Gruntfile to help manage front end tasks like compiling less/scss, compressing js, and checking coding standards. [[development:grunt|See the documentation]] to get started. | VuFind®, as of version 9.0, uses [[development:npm|NPM Scripts]] to help manage front end tasks like compiling and converting less/scss. Earlier releases used [[development:grunt|Grunt]]. |
===== Meeting Project Standards ===== | ===== Meeting Project Standards ===== |
| |
The VuFind project includes [[development:testing:unit_tests|unit tests]] and automated code style checks designed to insure the consistency and integrity of the code. Whenever a Git commit is made or a GitHub pull request is opened, [[development:testing:continuous_integration|continuous integration]] processes run to validate the changes, and alerts will be thrown if anything breaks. | The VuFind® project includes [[development:testing:unit_tests|unit tests]] and automated code style checks designed to insure the consistency and integrity of the code. Whenever a Git commit is made or a GitHub pull request is opened, [[development:testing:continuous_integration|continuous integration]] processes run to validate the changes, and alerts will be thrown if anything breaks. |
| |
| ==== Checking Everything ==== |
| |
| While you can open a pull request and check for problems after the fact through GitHub's interface, it is also possible to run checks prior to submission, which may save you some time. To run all the tests and code quality checks locally, run the following command from your VuFind® home directory: |
| |
| <code> |
| composer run qa |
| </code> |
| |
==== Tests ==== | ==== Tests ==== |
==== Style ==== | ==== Style ==== |
| |
For style compliance, VuFind uses [[https://github.com/squizlabs/PHP_CodeSniffer|PHP_CodeSniffer]] and [[https://github.com/FriendsOfPHP/PHP-CS-Fixer|PHP-CS-fixer]], each of which is capable of detecting (and sometimes automatically fixing) different issues. In recent versions of VuFind, these tools will be installed automatically by Composer. | For style compliance, VuFind® uses [[https://github.com/squizlabs/PHP_CodeSniffer|PHP_CodeSniffer]] and [[https://github.com/FriendsOfPHP/PHP-CS-Fixer|PHP-CS-fixer]], each of which is capable of detecting (and sometimes automatically fixing) different issues. In recent versions of VuFind®, these tools will be installed automatically by Composer. |
| |
To test style compliance with PHP_CodeSniffer while in your VuFind directory, you can test a single file with: | To test style compliance with PHP_CodeSniffer while in your VuFind® directory, you can test a single file with: |
| |
<code> | <code> |
vendor/bin/phpcs --standard=PEAR [file] | vendor/bin/phpcs --standard=$VUFIND_HOME/tests/phpcs.xml [file] |
</code> | </code> |
| |
</code> | </code> |
| |
To automatically fix additional issues with php-cs-fixer, from the base of your VuFind directory, run: | To automatically fix additional issues with php-cs-fixer, from the base of your VuFind® directory, run: |
| |
<code> | <code> |
</code> | </code> |
| |
If you are unwilling or unable to run these tools locally, note that if you open a pull request against the [[https://github.com/vufind-org/vufind|main VuFind repo]], they will be automatically run by [[development:testing:continuous_integration|continuous integration]] and you can view a list of issues in the resulting Travis report. Before you spend time manually fixing anything, you can post a comment on the pull request to ask for assistance with running the automatic processes. | If you are unwilling or unable to run these tools locally, note that if you open a pull request against the [[https://github.com/vufind-org/vufind|main VuFind® repo]], they will be automatically run by [[development:testing:continuous_integration|continuous integration]] and you can view a list of issues in the resulting report. Before you spend time manually fixing anything, you can post a comment on the pull request to ask for assistance with running the automatic processes. |
| |
| ==== Static Analysis ==== |
| |
| VuFind® uses [[https://phpstan.org/|PHPStan]] for static code analysis; it helps detect common programming errors like incorrect types, unused variables, etc. Paying attention to PHPStan reports can help you write better-quality code and avoid subtle bugs. To run a PHPStan test, you can use this command: |
| |
| <code> |
| vendor/bin/phing phpstan-console |
| </code> |
---- struct data ---- | ---- struct data ---- |
| properties.Page Owner : |
---- | ---- |
| |