Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Create PHP docs with Doxygen instead of phpdocumentor
This allows us to easier publish our docs and they follow a de facto default for MediaWiki (mediawiki/core, oojs-ui, and all other libraries using doxgen to generate php docs). Bug: T105134 Change-Id: Ia6b7e2c48c5459478a7ddb5de3b23e90a4ced9df
- Loading branch information
Showing
6 changed files
with
122 additions
and
123 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
# Configuration file for Doxygen | ||
|
||
PROJECT_NAME = MobileFrontend | ||
PROJECT_BRIEF = Mobile optimised frontend for MediaWiki | ||
|
||
OUTPUT_DIRECTORY = docs | ||
HTML_OUTPUT = php | ||
|
||
JAVADOC_AUTOBRIEF = YES | ||
QT_AUTOBRIEF = YES | ||
|
||
WARN_NO_PARAMDOC = YES | ||
|
||
INPUT = README.md ./ | ||
EXCLUDE_PATTERNS = */vendor/* | ||
EXCLUDE_PATTERNS += */docs/* | ||
EXCLUDE_PATTERNS += */node_modules/* | ||
FILE_PATTERNS = *.php | ||
RECURSIVE = YES | ||
# Requires doxygen 1.8.3+ | ||
USE_MDFILE_AS_MAINPAGE = README.md | ||
|
||
HTML_DYNAMIC_SECTIONS = YES | ||
GENERATE_TREEVIEW = YES | ||
TREEVIEW_WIDTH = 250 | ||
|
||
GENERATE_LATEX = NO | ||
|
||
HAVE_DOT = YES | ||
DOT_FONTNAME = Helvetica | ||
DOT_FONTSIZE = 10 | ||
TEMPLATE_RELATIONS = YES | ||
CALL_GRAPH = NO | ||
CALLER_GRAPH = NO | ||
# Makes dot run faster. Requires graphviz >1.8.10 | ||
DOT_MULTI_TARGETS = YES |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
MobileFrontend Extension | ||
======================== | ||
|
||
The MobileFrontend extension adds a mobile view to your mediawiki instance. | ||
|
||
Installation | ||
------------ | ||
|
||
See [https://www.mediawiki.org/wiki/Extension:MobileFrontend\#Installation](https://www.mediawiki.org/wiki/Extension:MobileFrontend#Installation "https://www.mediawiki.org/wiki/Extension:MobileFrontend#Installation") | ||
|
||
Configuration | ||
------------- | ||
|
||
See [https://www.mediawiki.org/wiki/Extension:MobileFrontend\#Configuration\_settings](https://www.mediawiki.org/wiki/Extension:MobileFrontend#Configuration_settings "https://www.mediawiki.org/wiki/Extension:MobileFrontend#Configuration_settings") | ||
|
||
Development | ||
----------- | ||
|
||
### Coding conventions | ||
|
||
Please follow the coding conventions of MobileFrontend: [https://www.mediawiki.org/wiki/MobileFrontend/Coding\_conventions](https://www.mediawiki.org/wiki/MobileFrontend/Coding_conventions "https://www.mediawiki.org/wiki/MobileFrontend/Coding_conventions") | ||
|
||
#### Git hooks | ||
|
||
Git hooks are provided in the dev-scripts directory to assist with adhering to JavaScript code standards, optimizing PNG files, etc. Running these hooks requires node.js, NPM, and grunt. | ||
|
||
Install like so: | ||
|
||
make installhooks | ||
|
||
If you are not running Vagrant, be sure to set your MEDIAWIKI\_URL env variable to your local index path, e.g. 'MEDIAWIKI\_URL=[http://localhost/index.php/](http://localhost/index.php/ "http://localhost/index.php/")' | ||
|
||
### Committing | ||
|
||
Commits are important as they give the reviewer more information to successfully review your code and find errors or potential problems you might not have thought of. | ||
|
||
Commits are also useful when troubleshooting issues and refactoring. If it's not clear why a line of code is in the repository important bug fixes could be lost. | ||
|
||
Commits should be as minor as possible. Please avoid removing unrelated console.log statements, fixing unrelated whitespace etc. do that in a separate commit which mentions the word cleanup. | ||
|
||
First line commit should summarise the commit with bug it fixes if applicable. e.g. Fix problem with toggling see bug x. Second line should be blank. Third line should go into detail where necessary providing links to blog posts/other bugs to provide more background. Mention the platforms/browsers the change is for where necessary, e.g.: | ||
|
||
- 'this is a problem on Android but not OSX see http://<url></url> which explains problem in detail' | ||
- 'this is a workaround for a known bug in opera mobile see see http://<url></url>' | ||
|
||
### Testing | ||
|
||
#### Unit tests | ||
|
||
To run the full test suite run: | ||
|
||
make tests | ||
|
||
To run only PHP tests: | ||
|
||
make phpunit | ||
|
||
To run only JS tests: | ||
|
||
make qunit | ||
|
||
#### Selenium tests | ||
|
||
For information on how to run Selenium tests please see README file in tests/browser directory. | ||
|
||
### Releasing | ||
|
||
A new version of MobileFrontend is released every two weeks. A developer needs to generate release notes and create a file with the title "RELEASE-NOTES-X.X.X.mediawiki" where "X.X.X" is the software version. Once a new release is due, the contents of the above file is moved to HISTORY.mediawiki and the file itself is deleted. Ideally, we need to create a bot similar to [https://wikitech.wikimedia.org/wiki/Jouncebot](https://wikitech.wikimedia.org/wiki/Jouncebot "https://wikitech.wikimedia.org/wiki/Jouncebot") that reads a calendar and pings a developer on \#wikimedia-mobile to remind them about a release. | ||
|
||
#### Generating release notes | ||
|
||
You can generate release notes by running (replace {branch name / commit SHA}): | ||
|
||
make releasenotes from={branch name / commit SHA} to={branch name / commit SHA} | ||
|
||
Which will output a list of commits between two branches or commit SHAs. | ||
|
||
#### Versioning | ||
|
||
Adhere to [http://semver.org/](http://semver.org/ "http://semver.org/") when changing versions. | ||
|
||
> Given a version number MAJOR.MINOR.PATCH, increment the: | ||
> | ||
> MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards-compatible manner, and PATCH version when you make backwards-compatible bug fixes. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,16 +1,12 @@ | ||
{ | ||
"require-dev": { | ||
"jakub-onderka/php-parallel-lint": "0.9", | ||
"mediawiki/mediawiki-codesniffer": "0.3.0", | ||
"phpdocumentor/phpdocumentor": "^2.8" | ||
"mediawiki/mediawiki-codesniffer": "0.3.0" | ||
}, | ||
"scripts": { | ||
"test": [ | ||
"parallel-lint . --exclude vendor", | ||
"phpcs --standard=vendor/mediawiki/mediawiki-codesniffer/MediaWiki --extensions=php,php5,inc --ignore=vendor -p ." | ||
], | ||
"doc": [ | ||
"phpdoc" | ||
] | ||
} | ||
} |
This file was deleted.
Oops, something went wrong.