From e27fd2fc2af084ab2acc8bc7511870e1b0a10795 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 31 Aug 2021 11:02:36 +0100 Subject: [PATCH 1/4] Normalize headings in markdown files Start each file with a h1-level heading, and increment levels for section headings one at a time. These correspond to rules MD041 and MD001 of markdownlint, respectively. --- CHANGELOG.md | 60 +++++++++++++++++++++++++-------------------------- GOVERNANCE.md | 2 ++ LICENSE.md | 2 +- README.md | 2 ++ USAGE.md | 32 +++++++++++++-------------- 5 files changed, 51 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa10d0b..f559481 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,17 +1,17 @@ -## Changelog +# Changelog Since v0.10.0 this project adheres to [Semantic Versioning](http://semver.org/) and [Keep a Changelog](http://keepachangelog.com/). -### Upcoming version +## Upcoming version -#### Added +### Added * New exception class `WikimateException` for API communication errors ([#136]) * Usage documentation about maximum lag and retries ([#134]) * New `CONTRIBUTING.md` file with contribution guidelines ([#135]) -#### Changed +### Changed * Centralized API communication checks in `WikiPage::request()` ([#136]) * Added additional context to `README.md` ([#127]) @@ -24,70 +24,70 @@ and may require changes in applications that invoke these methods:_ * Error return values for `WikiPage::getSection()` changed from `false` to `null` ([#129]) * `Wikimate::login()` error code `'login'` is now `'auth'`, also used by `logout()` ([#132]) -#### Fixed +### Fixed * Fixed one error return value in `WikiPage::setText()` ([#129]) * Fixed exception type/message for `$keyNames` parameter to `WikiPage::getAllSections()` ([#133]) -#### Removed +### Removed * Method `Wikimate::debugCurlConfig()`, deprecated since v0.10.0 ([#128]) -### Version 0.15.0 - 2021-08-26 +## Version 0.15.0 - 2021-08-26 -#### Added +### Added * New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123]) * New method `Wikimate::logout()` ([#124]) * Added post-release update steps to `GOVERNANCE.md` ([#125]) -#### Changed +### Changed * Updated `Wikimate::token()` to remember CSRF token and reduce API calls ([#122]) -#### Fixed +### Fixed * Fixed format of user agent string ([#121]) -### Version 0.14.0 - 2021-08-24 +## Version 0.14.0 - 2021-08-24 -#### Added +### Added * Support for the maxlag parameter (with retries) in API requests ([#112]) * Support for getting/setting user agent for API requests ([#107]) * Added missing PHPDoc comments for properties, constants, and more ([#109]) -#### Changed +### Changed * Changed API requests from deprecated PHP format to JSON format ([#111]) * Grouped sections and added table of contents in `USAGE.md` ([#108]) -#### Fixed +### Fixed * Removed null returns from destructors & fixed PHPDoc comments ([#114]) * Fixed sections object initialization warning in PHP 7.4+ ([#118]) -### Version 0.13.0 - 2021-07-05 +## Version 0.13.0 - 2021-07-05 -#### Added +### Added * Added more debug logging of MediaWiki requests and responses ([#101], [#106]) * New `GOVERNANCE.md` file to explicitly codify the project management principles and provide guidelines for maintenance tasks ([#83], [#105]) -#### Changed +### Changed * Modernized token handling for login and data-modifying actions. Requires MediaWiki v1.27 or newer. ([#100], [#106]) -#### Fixed +### Fixed * Prevented PHP notice in `WikiFile::getInfo()` for moved or deleted file ([#85]) * Fixed capitalization of a built-in PHP class in a comment ([#106]) -### Version 0.12.0 - 2017-02-03 +## Version 0.12.0 - 2017-02-03 -#### Added +### Added * New class WikiFile to retrieve properties of a file, and download and upload its contents. All properties pertain to the current revision of the file, or a specific older revision. @@ -95,15 +95,15 @@ and may require changes in applications that invoke these methods:_ * WikiFile also provides the file history and the ability to delete a file or an older revision of it ([#76]) -### Version 0.11.0 - 2016-11-16 +## Version 0.11.0 - 2016-11-16 -#### Added +### Added * Support for a section name (in addition to an index) in `WikiPage::setText()` and `WikiPage::setSection()` ([#45]) * Support for optional domain at authentication ([#28]) -#### Changed +### Changed * Updated `WikiPage::getSection()` to include subsections by default; disabling the new `$includeSubsections` option reverts to the old behavior @@ -114,7 +114,7 @@ and may require changes in applications that invoke these methods:_ This may require changes in your application's error handling ([#63]) * Restructured and improved documentation ([#32], [#34], [#47], [#49], [#61]) -#### Fixed +### Fixed * Ensured use of Wikimate user agent by Requests library ([#64]) * Corrected handling an invalid page title ([#57]) @@ -124,24 +124,24 @@ and may require changes in applications that invoke these methods:_ * Fixed passing the return value in `WikiPage::setSection()` ([#30]) * Corrected call to `Wikimate::debugRequestsConfig()` ([#30]) -### Version 0.10.0 - 2014-06-24 +## Version 0.10.0 - 2014-06-24 -#### Changed +### Changed * Switched to using the *Requests* library instead of Curl ([#25]) -### Version 0.9 - 2014-06-13 +## Version 0.9 - 2014-06-13 * Bumped version for stable release -### Version 0.5 - 2011-09-09 +## Version 0.5 - 2011-09-09 * Removed the use of constants in favour of constructor arguments * Added checks that throw an exception if can't write to wikimate_cookie.txt * Throws exception if curl library not loaded * Throws exception if can't login -### Version 0.4 - 2011-01-15 +## Version 0.4 - 2011-01-15 * Added `WikiPage::newSection()` and `WikiPage::setSection()` (shortcuts to `WikiPage::setText()`) * Added the ability to get individual sections of the article with `WikiPage::getSection()` @@ -150,7 +150,7 @@ and may require changes in applications that invoke these methods:_ with `WikiPage::getSectionOffsets()` * Added the ability to see how many sections are on a page with `WikiPage::getNumSections()` -### Version 0.3 - 2010-12-26 +## Version 0.3 - 2010-12-26 * Initial commit diff --git a/GOVERNANCE.md b/GOVERNANCE.md index e2cca5c..e8385da 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,3 +1,5 @@ +# Governance + The Wikimate project strives for a transparent and welcoming maintenance process. Below are some guidelines for current and prospective maintainers. Anyone is welcome to propose changes to this document via issues or pull requests. diff --git a/LICENSE.md b/LICENSE.md index d06490d..f2a4254 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -## MIT License +# MIT License Copyright (c) 2010-2021 Robert McLeod, Frans P. de Vries, and [contributors](https://github.com/hamstar/Wikimate/graphs/contributors) diff --git a/README.md b/README.md index 6261447..977ab69 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Wikimate + Wikimate is a PHP wrapper for the [MediaWiki Action API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page) that aims to be very easy to use. diff --git a/USAGE.md b/USAGE.md index 730d737..09e4feb 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,4 +1,4 @@ -## Usage +# Usage - [Introduction](#introduction) - [Getting a page object](#getting-a-page-object) @@ -16,7 +16,7 @@ * [Maximum lag and retries](#maximum-lag-and-retries) * [Handling errors and exceptions](#handling-errors-and-exceptions) -### Introduction +## Introduction In your script file (e.g. `index.php`), include Wikimate's `globals.php` file, and create a new `Wikimate` object with the target wiki's API address. @@ -52,7 +52,7 @@ Currently only output from the logon process is printed for debugging. Assuming you were able to log in, you're now ready to fully use the API. The next sections provide example code for several common tasks. -### Getting a page object +## Getting a page object Once logged in you can start playing around with pages. If the title given to the WikiPage object is invalid, @@ -71,7 +71,7 @@ echo $page->getNumSections(); echo $page->getSectionOffsets(); ``` -#### Reading... +### Reading... You can get the text of the page by using the `getText()` method which returns the text that was obtained when the page object was created. @@ -133,7 +133,7 @@ Array An `UnexpectedValueException` is thrown if an unsupported value is supplied for the `$keyNames` parameter. -#### Writing... +### Writing... You can modify the whole article using the `setText()` method: @@ -174,7 +174,7 @@ $page->newSection($sectionTitle, $text); For the latter method, the $sectionTitle is also used as part of the edit summary description. -#### Deleting... +### Deleting... If the account you're using has delete permissions, you can delete entire pages with `delete()`: @@ -187,7 +187,7 @@ $page->delete('The page was created accidentally in the first place'); If you pass in a message argument, it will be recorded as the reason for the deletion. -### Getting a file object +## Getting a file object Once connected you can also start playing around with files. @@ -216,7 +216,7 @@ echo $file->getMime(); echo $file->getAspectRatio(); ``` -#### Downloading... +### Downloading... You can obtain the data of the file by using the `downloadData()` method and use it in your script, or write it directly to a local file via the `downloadFile()` method. @@ -227,7 +227,7 @@ $data = $file->downloadData(); $result = $file->downloadFile('/path/to/sitelogo.png'); ``` -#### Uploading... +### Uploading... You can upload data from your script to the file by using the `uploadData()` method, or read it directly from a local file via the `uploadFile()` method. @@ -256,7 +256,7 @@ if ($file->exists()) die('Example image already exists'); $result = uploadFromUrl('https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg', 'Adopt Wiki example image'); ``` -#### Accessing revisions... +### Accessing revisions... The revision history of a file can be obtained as an array with a properties array per revision: @@ -301,7 +301,7 @@ echo $file->getAspectRatio(2); echo $file->getUrl('2016-11-22T33:44:55Z'); ``` -#### Deleting... +### Deleting... If the account you're using has delete permissions, you can delete files as well: @@ -323,9 +323,9 @@ $archivename = $file->getArchivename(1); $file->revert($archivename, 'Revert to the previous release'); ``` -### Other stuff +## Other stuff -#### Running custom queries +### Running custom queries Wanna run your own queries? You can use the edit and query commands in Wikimate: @@ -350,7 +350,7 @@ $array_result = $wiki->edit($data); Both methods return an array of the MediaWiki API result. -#### Customizing the user agent +### Customizing the user agent API requests are made over HTTP with a user agent string to identify the client to the server. By default the user agent is formatted as: @@ -368,7 +368,7 @@ $wiki->setUserAgent('Custom Prefix - ' . $useragent); In order to use a custom user agent for all requests in the session, call this method before invoking `Wikimate::login()`. -#### Maximum lag and retries +### Maximum lag and retries API requests include the [maxlag parameter](https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Maxlag_parameter) so they time out when the server's time to respond exceeds the specified lag. @@ -380,7 +380,7 @@ for the number of seconds recommended by the server, and then retried. Retries continue indefinitely, unless limited via `$wiki->setMaxretries()`. If a limited number of retries runs out, `WikimateException` is thrown. -#### Handling errors and exceptions +### Handling errors and exceptions Did something go wrong? Check the error array: From b7c44329bf905dff0e520cca45de881d719b8196 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 31 Aug 2021 11:05:40 +0100 Subject: [PATCH 2/4] Improvements to markdown files - Add introductory context - Reword the introductory paragraphs of GOVERNANCE.md into a proper section - Fix a typo in CONTRIBUTING.md - Apply various fixes recommended by markdownlint --- CHANGELOG.md | 4 +++- CONTRIBUTING.md | 5 +++-- GOVERNANCE.md | 20 +++++++++++++------- README.md | 4 +++- USAGE.md | 3 ++- 5 files changed, 24 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f559481..a29977d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Changelog +This page lists the changes that were done in each version of Wikimate. + Since v0.10.0 this project adheres to [Semantic Versioning](http://semver.org/) and [Keep a Changelog](http://keepachangelog.com/). @@ -9,6 +11,7 @@ and [Keep a Changelog](http://keepachangelog.com/). * New exception class `WikimateException` for API communication errors ([#136]) * Usage documentation about maximum lag and retries ([#134]) +* New GitHub Action to enforce updates to `CHANGELOG.md` ([#131]) * New `CONTRIBUTING.md` file with contribution guidelines ([#135]) ### Changed @@ -16,7 +19,6 @@ and [Keep a Changelog](http://keepachangelog.com/). * Centralized API communication checks in `WikiPage::request()` ([#136]) * Added additional context to `README.md` ([#127]) * Added semi-linear merge recommendation to `GOVERNANCE.md` ([#130]) -* Added GitHub Action to enforce updates to `CHANGELOG.md` ([#131]) _The following two entries are backwards incompatible API changes and may require changes in applications that invoke these methods:_ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4291fc..8c0df9a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contribution guidelines -The Wikimate projects welcomes contributions of [all kinds](https://allcontributors.org/docs/en/emoji-key), +The Wikimate project welcomes contributions of [all kinds](https://allcontributors.org/docs/en/emoji-key), no matter how small! Feel free to open [an issue](https://github.com/hamstar/Wikimate/issues/new) to discuss your suggestion or request, @@ -27,4 +27,5 @@ Below are some guidelines that might help you prepare your contribution. When writing prose, break lines [semantically](https://rhodesmill.org/brandon/2012/one-sentence-per-line/). We don't have a strict maximum line length (especially since things like long URLs can easily surpass them), - but you should start thinking about breaking lines once they're approaching 100 characters in length. + but you should start thinking about breaking lines + once they're approaching 100 characters in length. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index e8385da..ee2407b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,8 +1,12 @@ # Governance +This page contains guidelines for current and prospective maintainers. + +## Process transparency and contributor onboarding + The Wikimate project strives for a transparent and welcoming maintenance process. -Below are some guidelines for current and prospective maintainers. -Anyone is welcome to propose changes to this document via issues or pull requests. +Discussions are expected to happen in public channels, via issues or pull requests, +including proposals to change this document or the [contribution guidelines](CONTRIBUTING.md). Regular contributors are to be given collaborator status (which includes commit access, the ability to merge PRs, make releases, etc.). @@ -39,14 +43,14 @@ It should apply the following actions: to the appropriate version name and date (e.g. "Version 1.2.3 - 2020-12-31") and add a new "Upcoming version" section heading above it, with the contents "No changes yet."; -2. Edit the README and replace all references +2. Edit `README.md` and replace all references to the previous version number and release date with the corresponding data for the new version; 3. Update all version references in `Wikimate.php` to the new version. -Once this PR is merged, create a new release -in https://github.com/hamstar/Wikimate/releases/new +Once this PR is merged, create a new release +in (collaborator status is required for this step). The version tag and the title of the release notes should be in the format `v1.2.3` @@ -57,5 +61,7 @@ of the relevant section in `CHANGELOG.md`. Finally, update the Wikimate entry on [Packagist](https://packagist.org/packages/hamstar/wikimate) (via the "Update Now" link in the right sidebar) -and the corresponding row in the [PHP libraries table](https://www.mediawiki.org/wiki/API:Client_code/All#PHP) on MediaWiki.org, -along with Wikipedia's [PHP bot framework table](https://en.wikipedia.org/wiki/Wikipedia:PHP_bot_framework_table) if applicable. +and the corresponding row in MediaWiki.org's +[PHP libraries table](https://www.mediawiki.org/wiki/API:Client_code/All#PHP). +If applicable, also update Wikipedia's +[PHP bot frameworks table](https://en.wikipedia.org/wiki/Wikipedia:PHP_bot_framework_table). diff --git a/README.md b/README.md index 977ab69..9ea441f 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,9 @@ Then, download Wikimate, and initialise it by running `composer install` To use Wikimate within another project, you can add it as a composer dependency by adding the following to your `composer.json` file: - "hamstar/Wikimate": "0.15.0" +```json +"hamstar/Wikimate": "0.15.0" +``` ## Usage diff --git a/USAGE.md b/USAGE.md index 09e4feb..15940d3 100644 --- a/USAGE.md +++ b/USAGE.md @@ -118,7 +118,7 @@ $sections = $page->getAllSections(false, 2); The array looks like this: -``` +```text Array ( [intro] => bit between title and first section @@ -392,6 +392,7 @@ print_r($file->getError()); For MediaWiki API errors, the array contains the 'code' and 'info' key/value pairs [defined by the API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Errors_and_warnings#Errors). For other errors, the following key/value pairs are returned: + * 'auth' for Wikimate authentication (login & logout) problems * 'token' for Wikimate token problems * 'page' for WikiPage errors From 76cc5df7bbe385051ad571702fbef3b3a437f0b9 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 31 Aug 2021 19:33:58 +0100 Subject: [PATCH 3/4] Change list syntax in markdown files Use dashes for lists, and leave asterisks for emphasis. --- CHANGELOG.md | 112 +++++++++++++++++++++++++-------------------------- README.md | 6 +-- USAGE.md | 30 +++++++------- 3 files changed, 74 insertions(+), 74 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a29977d..4c4075f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,152 +9,152 @@ and [Keep a Changelog](http://keepachangelog.com/). ### Added -* New exception class `WikimateException` for API communication errors ([#136]) -* Usage documentation about maximum lag and retries ([#134]) -* New GitHub Action to enforce updates to `CHANGELOG.md` ([#131]) -* New `CONTRIBUTING.md` file with contribution guidelines ([#135]) +- New exception class `WikimateException` for API communication errors ([#136]) +- Usage documentation about maximum lag and retries ([#134]) +- New GitHub Action to enforce updates to `CHANGELOG.md` ([#131]) +- New `CONTRIBUTING.md` file with contribution guidelines ([#135]) ### Changed -* Centralized API communication checks in `WikiPage::request()` ([#136]) -* Added additional context to `README.md` ([#127]) -* Added semi-linear merge recommendation to `GOVERNANCE.md` ([#130]) +- Centralized API communication checks in `WikiPage::request()` ([#136]) +- Added additional context to `README.md` ([#127]) +- Added semi-linear merge recommendation to `GOVERNANCE.md` ([#130]) _The following two entries are backwards incompatible API changes and may require changes in applications that invoke these methods:_ -* Error return values for `WikiPage::getSection()` changed from `false` to `null` ([#129]) -* `Wikimate::login()` error code `'login'` is now `'auth'`, also used by `logout()` ([#132]) +- Error return values for `WikiPage::getSection()` changed from `false` to `null` ([#129]) +- `Wikimate::login()` error code `'login'` is now `'auth'`, also used by `logout()` ([#132]) ### Fixed -* Fixed one error return value in `WikiPage::setText()` ([#129]) -* Fixed exception type/message for `$keyNames` parameter to `WikiPage::getAllSections()` ([#133]) +- Fixed one error return value in `WikiPage::setText()` ([#129]) +- Fixed exception type/message for `$keyNames` parameter to `WikiPage::getAllSections()` ([#133]) ### Removed -* Method `Wikimate::debugCurlConfig()`, deprecated since v0.10.0 ([#128]) +- Method `Wikimate::debugCurlConfig()`, deprecated since v0.10.0 ([#128]) ## Version 0.15.0 - 2021-08-26 ### Added -* New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123]) -* New method `Wikimate::logout()` ([#124]) -* Added post-release update steps to `GOVERNANCE.md` ([#125]) +- New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123]) +- New method `Wikimate::logout()` ([#124]) +- Added post-release update steps to `GOVERNANCE.md` ([#125]) ### Changed -* Updated `Wikimate::token()` to remember CSRF token and reduce API calls ([#122]) +- Updated `Wikimate::token()` to remember CSRF token and reduce API calls ([#122]) ### Fixed -* Fixed format of user agent string ([#121]) +- Fixed format of user agent string ([#121]) ## Version 0.14.0 - 2021-08-24 ### Added -* Support for the maxlag parameter (with retries) in API requests ([#112]) -* Support for getting/setting user agent for API requests ([#107]) -* Added missing PHPDoc comments for properties, constants, and more ([#109]) +- Support for the maxlag parameter (with retries) in API requests ([#112]) +- Support for getting/setting user agent for API requests ([#107]) +- Added missing PHPDoc comments for properties, constants, and more ([#109]) ### Changed -* Changed API requests from deprecated PHP format to JSON format ([#111]) -* Grouped sections and added table of contents in `USAGE.md` ([#108]) +- Changed API requests from deprecated PHP format to JSON format ([#111]) +- Grouped sections and added table of contents in `USAGE.md` ([#108]) ### Fixed -* Removed null returns from destructors & fixed PHPDoc comments ([#114]) -* Fixed sections object initialization warning in PHP 7.4+ ([#118]) +- Removed null returns from destructors & fixed PHPDoc comments ([#114]) +- Fixed sections object initialization warning in PHP 7.4+ ([#118]) ## Version 0.13.0 - 2021-07-05 ### Added -* Added more debug logging of MediaWiki requests and responses ([#101], [#106]) -* New `GOVERNANCE.md` file to explicitly codify the project management principles +- Added more debug logging of MediaWiki requests and responses ([#101], [#106]) +- New `GOVERNANCE.md` file to explicitly codify the project management principles and provide guidelines for maintenance tasks ([#83], [#105]) ### Changed -* Modernized token handling for login and data-modifying actions. +- Modernized token handling for login and data-modifying actions. Requires MediaWiki v1.27 or newer. ([#100], [#106]) ### Fixed -* Prevented PHP notice in `WikiFile::getInfo()` for moved or deleted file ([#85]) -* Fixed capitalization of a built-in PHP class in a comment ([#106]) +- Prevented PHP notice in `WikiFile::getInfo()` for moved or deleted file ([#85]) +- Fixed capitalization of a built-in PHP class in a comment ([#106]) ## Version 0.12.0 - 2017-02-03 ### Added -* New class WikiFile to retrieve properties of a file, and download and upload its contents. +- New class WikiFile to retrieve properties of a file, and download and upload its contents. All properties pertain to the current revision of the file, or a specific older revision. ([#69], [#71], [#78], [#80]) -* WikiFile also provides the file history +- WikiFile also provides the file history and the ability to delete a file or an older revision of it ([#76]) ## Version 0.11.0 - 2016-11-16 ### Added -* Support for a section name (in addition to an index) +- Support for a section name (in addition to an index) in `WikiPage::setText()` and `WikiPage::setSection()` ([#45]) -* Support for optional domain at authentication ([#28]) +- Support for optional domain at authentication ([#28]) ### Changed -* Updated `WikiPage::getSection()` to include subsections by default; +- Updated `WikiPage::getSection()` to include subsections by default; disabling the new `$includeSubsections` option reverts to the old behavior of returning only the text until the first subsection ([#55]) -* Improved section processing in `WikiPage::getText()` ([#33], [#37], [#50]) -* Ensured that MediaWiki API error responses appear directly in `WikiPage::$error` +- Improved section processing in `WikiPage::getText()` ([#33], [#37], [#50]) +- Ensured that MediaWiki API error responses appear directly in `WikiPage::$error` rather than a nested 'error' array. This may require changes in your application's error handling ([#63]) -* Restructured and improved documentation ([#32], [#34], [#47], [#49], [#61]) +- Restructured and improved documentation ([#32], [#34], [#47], [#49], [#61]) ### Fixed -* Ensured use of Wikimate user agent by Requests library ([#64]) -* Corrected handling an invalid page title ([#57]) -* Fixed returning an empty section without header in `WikiPage::getSection()` ([#52]) -* Prevented PHP Notices in several methods ([#43], [#67]) -* Corrected handling an unknown section parameter in `WikiPage::getSection()` ([#41]) -* Fixed passing the return value in `WikiPage::setSection()` ([#30]) -* Corrected call to `Wikimate::debugRequestsConfig()` ([#30]) +- Ensured use of Wikimate user agent by Requests library ([#64]) +- Corrected handling an invalid page title ([#57]) +- Fixed returning an empty section without header in `WikiPage::getSection()` ([#52]) +- Prevented PHP Notices in several methods ([#43], [#67]) +- Corrected handling an unknown section parameter in `WikiPage::getSection()` ([#41]) +- Fixed passing the return value in `WikiPage::setSection()` ([#30]) +- Corrected call to `Wikimate::debugRequestsConfig()` ([#30]) ## Version 0.10.0 - 2014-06-24 ### Changed -* Switched to using the *Requests* library instead of Curl ([#25]) +- Switched to using the *Requests* library instead of Curl ([#25]) ## Version 0.9 - 2014-06-13 -* Bumped version for stable release +- Bumped version for stable release ## Version 0.5 - 2011-09-09 -* Removed the use of constants in favour of constructor arguments -* Added checks that throw an exception if can't write to wikimate_cookie.txt -* Throws exception if curl library not loaded -* Throws exception if can't login +- Removed the use of constants in favour of constructor arguments +- Added checks that throw an exception if can't write to wikimate_cookie.txt +- Throws exception if curl library not loaded +- Throws exception if can't login ## Version 0.4 - 2011-01-15 -* Added `WikiPage::newSection()` and `WikiPage::setSection()` (shortcuts to `WikiPage::setText()`) -* Added the ability to get individual sections of the article with `WikiPage::getSection()` -* Added the ability to get all sections in an array with `WikiPage::getAllSections()` -* Added the ability to get an array showing section offsets and lengths in the page wikicode +- Added `WikiPage::newSection()` and `WikiPage::setSection()` (shortcuts to `WikiPage::setText()`) +- Added the ability to get individual sections of the article with `WikiPage::getSection()` +- Added the ability to get all sections in an array with `WikiPage::getAllSections()` +- Added the ability to get an array showing section offsets and lengths in the page wikicode with `WikiPage::getSectionOffsets()` -* Added the ability to see how many sections are on a page with `WikiPage::getNumSections()` +- Added the ability to see how many sections are on a page with `WikiPage::getNumSections()` ## Version 0.3 - 2010-12-26 -* Initial commit +- Initial commit [#25]: https://github.com/hamstar/Wikimate/pull/25 [#28]: https://github.com/hamstar/Wikimate/pull/28 diff --git a/README.md b/README.md index 9ea441f..2ce4d32 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ Wikimate is a PHP wrapper for the that aims to be very easy to use. It currently consists of three classes: -* **Wikimate** – Serves as a loader and manager for different wiki objects (e.g. pages). -* **WikiPage** – Provides an interface to getting/editing pages or sections of them. -* **WikiFile** – Provides an interface to downloading/uploading files and getting their properties. +- **Wikimate** – Serves as a loader and manager for different wiki objects (e.g. pages). +- **WikiPage** – Provides an interface to getting/editing pages or sections of them. +- **WikiFile** – Provides an interface to downloading/uploading files and getting their properties. The [latest released version](https://github.com/hamstar/Wikimate/releases) of Wikimate is v0.15.0, released on Aug 26, 2021. diff --git a/USAGE.md b/USAGE.md index 15940d3..15ca11a 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2,19 +2,19 @@ - [Introduction](#introduction) - [Getting a page object](#getting-a-page-object) - * [Reading...](#reading) - * [Writing...](#writing) - * [Deleting...](#deleting) + - [Reading...](#reading) + - [Writing...](#writing) + - [Deleting...](#deleting) - [Getting a file object](#getting-a-file-object) - * [Downloading...](#downloading) - * [Uploading...](#uploading) - * [Accessing revisions...](#accessing-revisions) - * [Deleting...](#deleting-1) + - [Downloading...](#downloading) + - [Uploading...](#uploading) + - [Accessing revisions...](#accessing-revisions) + - [Deleting...](#deleting-1) - [Other stuff](#other-stuff) - * [Running custom queries](#running-custom-queries) - * [Customizing the user agent](#customizing-the-user-agent) - * [Maximum lag and retries](#maximum-lag-and-retries) - * [Handling errors and exceptions](#handling-errors-and-exceptions) + - [Running custom queries](#running-custom-queries) + - [Customizing the user agent](#customizing-the-user-agent) + - [Maximum lag and retries](#maximum-lag-and-retries) + - [Handling errors and exceptions](#handling-errors-and-exceptions) ## Introduction @@ -393,10 +393,10 @@ For MediaWiki API errors, the array contains the 'code' and 'info' key/value pai [defined by the API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Errors_and_warnings#Errors). For other errors, the following key/value pairs are returned: -* 'auth' for Wikimate authentication (login & logout) problems -* 'token' for Wikimate token problems -* 'page' for WikiPage errors -* 'file' for WikiFile errors +- 'auth' for Wikimate authentication (login & logout) problems +- 'token' for Wikimate token problems +- 'page' for WikiPage errors +- 'file' for WikiFile errors In case of an unexpected error while communicating with the API, i.e. receiving an HTML response or an invalid JSON response, From 6dd37f2b19d39fe8851564066f48afce969338bc Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Tue, 31 Aug 2021 11:06:18 +0100 Subject: [PATCH 4/4] Add GitHub Action to run markdownlint in markdown files --- .github/workflows/pull-request-checks.yml | 12 ++++++++--- .markdownlint.yml | 26 +++++++++++++++++++++++ CHANGELOG.md | 2 ++ 3 files changed, 37 insertions(+), 3 deletions(-) create mode 100644 .markdownlint.yml diff --git a/.github/workflows/pull-request-checks.yml b/.github/workflows/pull-request-checks.yml index e1182ac..21d5515 100644 --- a/.github/workflows/pull-request-checks.yml +++ b/.github/workflows/pull-request-checks.yml @@ -1,11 +1,17 @@ name: "Pull Request Checks" on: pull_request jobs: - # Enforces the update of a changelog file on every pull request + # Enforce the update of the changelog file check-changelog-change: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: dangoslen/changelog-enforcer@v2 - with: - versionPattern: '### (Version \\d+\\.\\d+\\.\\d* - \\d{4}-\\d{2}-\\d{2}|Upcoming version)' + # Ensure markdown files are formatted consistently + lint-markdown-files: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: xt0rted/markdownlint-problem-matcher@v1 + - run: npm install -g markdownlint-cli + - run: markdownlint **/*.md diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..77046fd --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,26 @@ +# MD010/no-hard-tabs +MD010: + # Exclude code blocks + code_blocks: false + +# MD013/line-length +MD013: + # Custom length limit (default is 80) + line_length: 100 + # Exclude code blocks + code_blocks: false + +# MD024/no-duplicate-heading +MD024: + # Only check sibling headings + allow_different_nesting: true + +# MD026/no-trailing-punctuation +MD026: + # Trailing punctuation characters not allowed in headings + punctuation: ",;:!" + +# MD004/ul-style +MD004: + # Use dashes for lists, leaving asterisks for emphasis + style: "dash" diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c4075f..4ab1162 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and [Keep a Changelog](http://keepachangelog.com/). - Usage documentation about maximum lag and retries ([#134]) - New GitHub Action to enforce updates to `CHANGELOG.md` ([#131]) - New `CONTRIBUTING.md` file with contribution guidelines ([#135]) +- New GitHub Action to check markdown files ([#138]) ### Changed @@ -209,3 +210,4 @@ and may require changes in applications that invoke these methods:_ [#134]: https://github.com/hamstar/Wikimate/pull/134 [#135]: https://github.com/hamstar/Wikimate/pull/135 [#136]: https://github.com/hamstar/Wikimate/pull/136 +[#138]: https://github.com/hamstar/Wikimate/pull/138