From f946925e506e4233ff52c47aabde2e1814d32712 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Sun, 29 Aug 2021 19:36:26 +0100 Subject: [PATCH 1/2] Add CONTRIBUTING.md file --- CHANGELOG.md | 2 ++ CONTRIBUTING.md | 30 ++++++++++++++++++++++++++++++ GOVERNANCE.md | 15 ++++----------- README.md | 5 +++++ 4 files changed, 41 insertions(+), 11 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 61bc7ef..243e267 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and [Keep a Changelog](http://keepachangelog.com/). #### Added * Usage documentation about maximum lag and retries ([#134]) +* New `CONTRIBUTING.md` file with contribution guidelines ([#135]) #### Changed @@ -191,3 +192,4 @@ and may require changes in applications that invoke these methods:_ [#132]: https://github.com/hamstar/Wikimate/pull/132 [#133]: https://github.com/hamstar/Wikimate/pull/133 [#134]: https://github.com/hamstar/Wikimate/pull/134 +[#135]: https://github.com/hamstar/Wikimate/pull/135 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f4291fc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# Contribution guidelines + +The Wikimate projects 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, +or submit your changes directly as a +[pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) +if you prefer. + +Below are some guidelines that might help you prepare your contribution. + +1. **Limit pull requests limited to a single feature or bugfix.** + Unrelated changes should be sent as separate PRs. + The exception are minor cleanup changes, + which can be included (as a separate commit) in the PR that prompted them. +2. **Use atomic commits**. + Try to create commits that are as small as possible + while still representing a self-contained set of changes, + and use descriptive commit messages. + We recommend [these principles](https://chris.beams.io/posts/git-commit/#seven-rules) + for writing great commit messages (but they're not enforced, so don't sweat it 🙂). +3. **Include a `CHANGELOG.md` entry in every pull request**. + This makes it much easier to prepare releases, + and allows the author of each change to properly summarize it. +4. **Update the documentation in `USAGE.md` if necessary**. + 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. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 35418b4..70b0b89 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -17,22 +17,15 @@ if they would like to help maintaining the repository. This allows every change to be validated by at least another maintainer. That said, if there's no input by other maintainers in over a week, the maintainer who authored the pull request can merge their own PR. -3. **Pull requests should be limited to a single feature or bugfix.** - Unrelated changes should be sent as separate PRs. - The exception are minor cleanup changes, - which can be included (as a separate commit) in the PR that prompted them. -4. **Commits should be atomic** - (as small as possible while still representing a self-contained set of changes) - and have descriptive commit messages. -5. **Every pull request should include a `CHANGELOG.md` entry**. - This makes it much easier to prepare releases, - and allows the author of each change to properly summarize it. -6. **Pull requests should be rebased before merging**. +3. **Pull requests should be rebased before merging**. The merge should be done with the "Create a merge commit" option. This allows preserving individual atomic commits while keeping them grouped per PR, while avoiding crossing branches in the git history, which becomes a [semi-linear graph](https://devblogs.microsoft.com/devops/pull-requests-with-rebase/#semi-linear-merge). +Note: when creating or handling pull requests, +make sure their contents follow the [contribution guidelines](CONTRIBUTING.md). + ## Process for releasing a new version of Wikimate A PR should be created with all relevant changes to update the repository for the upcoming release. diff --git a/README.md b/README.md index 94bdb30..9d28c1e 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,11 @@ Assuming you were able to log in, you're now ready to fully use the API. See [USAGE.md](USAGE.md) for detailed example code to perform common tasks. +## Contributing + +As an open source project, Wikimate welcomes community contributions. +Please see [CONTRIBUTING.md](CONTRIBUTING.md) for information on how to contribute. + ## License This project is licensed under the MIT license. From 656e027da9b033080894cc7bc0c4d391cc598389 Mon Sep 17 00:00:00 2001 From: Waldir Pimenta Date: Sun, 29 Aug 2021 19:45:35 +0100 Subject: [PATCH 2/2] Format markdown files to break long lines Also reword some passages for clarity, readability or consistency --- CHANGELOG.md | 37 ++++++++++++++++++++++++------------- GOVERNANCE.md | 20 +++++++++++--------- README.md | 13 +++++++------ USAGE.md | 37 ++++++++++++++++++++++++++----------- 4 files changed, 68 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 243e267..1267817 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,9 +12,9 @@ and [Keep a Changelog](http://keepachangelog.com/). #### Changed -* 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]) +* 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:_ @@ -37,7 +37,7 @@ and may require changes in applications that invoke these methods:_ * New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123]) * New method `Wikimate::logout()` ([#124]) -* Added post-release update steps to GOVERNANCE.md ([#125]) +* Added post-release update steps to `GOVERNANCE.md` ([#125]) #### Changed @@ -58,7 +58,7 @@ and may require changes in applications that invoke these methods:_ #### Changed * Changed API requests from deprecated PHP format to JSON format ([#111]) -* Grouped sections and added table of contents in USAGE.md ([#108]) +* Grouped sections and added table of contents in `USAGE.md` ([#108]) #### Fixed @@ -70,11 +70,13 @@ and may require changes in applications that invoke these methods:_ #### 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]) +* 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. Requires MediaWiki v1.27 or newer. ([#100], [#106]) +* Modernized token handling for login and data-modifying actions. + Requires MediaWiki v1.27 or newer. ([#100], [#106]) #### Fixed @@ -85,21 +87,29 @@ and may require changes in applications that invoke these methods:_ #### 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. ([#69], [#71], [#78], [#80]) -* WikiFile also provides the file history and the ability to delete a file or an older revision of it ([#76]) +* 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 + 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) in `WikiPage::setText()` and `WikiPage::setSection()` ([#45]) +* 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 -* 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]) +* 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` rather than a nested 'error' array ([#63]) -- this may require changes in your application's error handling +* 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]) #### Fixed @@ -134,7 +144,8 @@ and may require changes in applications that invoke these methods:_ * 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 array showing section offsets and lengths in the page wikicode with `WikiPage::getSectionOffsets()` +* 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()` ### Version 0.3 - 2010-12-26 diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 70b0b89..e2cca5c 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -4,14 +4,15 @@ Anyone is welcome to propose changes to this document via issues or pull request Regular contributors are to be given collaborator status (which includes commit access, the ability to merge PRs, make releases, etc.). -Note that at the moment this can only be done by the repository owner, [@hamstar](https://github.com/hamstar). +Note that at the moment this can only be done by the repository owner, +[@hamstar](https://github.com/hamstar). Contributors that have had a few PRs merged are encouraged to ask for collaborator access, if they would like to help maintaining the repository. -## Guidelines for commits and pull requests +## Guidelines for pull requests -1. **Every change should be made via pull requests**, - rather than as direct commits to the `master` branch +1. **Every change should be made via pull requests**. + Do not make commits directly to the `master` branch (except for very minor ones such as spelling fixes). 2. **Maintainers should not merge their own pull requests**. This allows every change to be validated by at least another maintainer. @@ -20,7 +21,7 @@ if they would like to help maintaining the repository. 3. **Pull requests should be rebased before merging**. The merge should be done with the "Create a merge commit" option. This allows preserving individual atomic commits while keeping them grouped per PR, - while avoiding crossing branches in the git history, which becomes a + and avoiding crossing branches in the git history, which becomes a [semi-linear graph](https://devblogs.microsoft.com/devops/pull-requests-with-rebase/#semi-linear-merge). Note: when creating or handling pull requests, @@ -28,7 +29,7 @@ make sure their contents follow the [contribution guidelines](CONTRIBUTING.md). ## Process for releasing a new version of Wikimate -A PR should be created with all relevant changes to update the repository for the upcoming release. +Create a PR with all relevant changes to update the repository for the upcoming release. (See [#81](https://github.com/hamstar/Wikimate/pull/81) for an example.) It should apply the following actions: @@ -42,16 +43,17 @@ It should apply the following actions: 3. Update all version references in `Wikimate.php` to the new version. -Once this PR is merged, a new release should be created +Once this PR is merged, create a new release in https://github.com/hamstar/Wikimate/releases/new (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 +The version tag and the title of the release notes should be in the format `v1.2.3` (following [SemVer](http://semver.org/) conventions to determine which part of the version number to increase). The body of the release notes should be a summary of the contents 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) +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. diff --git a/README.md b/README.md index 9d28c1e..6261447 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@ It currently consists of three classes: * **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. It requires MediaWiki v1.27 or newer. +is v0.15.0, released on Aug 26, 2021. +It requires MediaWiki v1.27 or newer. See [CHANGELOG.md](CHANGELOG.md) for the detailed version history. ## Installation @@ -16,14 +17,14 @@ See [CHANGELOG.md](CHANGELOG.md) for the detailed version history. **Requirements: [PHP](https://php.net), and [Composer](https://getcomposer.org).** Before anything else, since Wikimate is written in PHP, a server-side language, -you will need to have PHP installed to run it. Install it with your preferred -package management tool (for example, on Ubuntu Linux you can run: -`sudo apt-get install php`) +you will need to have PHP installed to run it. +Install it with your preferred package management tool +(for example, on Ubuntu Linux you can run: `sudo apt-get install php`) Install Composer by following the instructions [here](https://getcomposer.org/doc/00-intro.md). -Then, download Wikimate, and initialise it by running `composer install` (or -`composer.bat install` if you're on Windows). +Then, download Wikimate, and initialise it by running `composer install` +(or `composer.bat install` if you're on Windows). To use Wikimate within another project, you can add it as a composer dependency by adding the following to your `composer.json` file: diff --git a/USAGE.md b/USAGE.md index 538957d..72dddd1 100644 --- a/USAGE.md +++ b/USAGE.md @@ -55,7 +55,8 @@ The next sections provide example code for several common tasks. ### Getting a page object Once logged in you can start playing around with pages. -If the title given to the WikiPage object is invalid, your `$page` object will be null. +If the title given to the WikiPage object is invalid, +your `$page` object will be null. ```php // create a new page object @@ -84,7 +85,8 @@ $wikiCode = $page->getText(); $wikiCode = $page->getText(true); ``` -You can get sections from the page as well, via the section index, or the section heading name: +You can get sections from the page as well, +via the section index or the section heading: ```php // get the part between the title and the first section @@ -128,7 +130,8 @@ Array ) ``` -An `UnexpectedValueException` is thrown if an unsupported value is supplied for the `$keyNames` parameter. +An `UnexpectedValueException` is thrown +if an unsupported value is supplied for the `$keyNames` parameter. #### Writing... @@ -181,7 +184,8 @@ you can delete entire pages with `delete()`: $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. +If you pass in a message argument, +it will be recorded as the reason for the deletion. ### Getting a file object @@ -214,7 +218,8 @@ echo $file->getAspectRatio(); #### 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. +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. ```php $data = $file->downloadData(); @@ -224,11 +229,16 @@ $result = $file->downloadFile('/path/to/sitelogo.png'); #### 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. Additionally, uploading from a URL is possible via the `uploadFromUrl()` method. +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. +Additionally, uploading from a URL is possible via the `uploadFromUrl()` method. -A comment for the file's history must be supplied, and for a new file the text for its associated description page can be provided as well. If no such text is passed, the comment will be used instead. +A comment for the file's history must be supplied, +and for a new file the text for its associated description page can be provided as well. +If no such text is passed, the comment will be used instead. -All upload methods guard against uploading data to an existing file, but allow this when the overwrite flag is set. +All upload methods guard against uploading data to an existing file, +but allow this when the overwrite flag is set. ```php // construct image $data for Site-logo.png @@ -265,7 +275,9 @@ foreach ($history as $revision => $properties) { } ``` -One specific revision can be requested by revision sequence number or by exact timestamp in the current history, as can its archive name. Invoking `getHistory(true[, ...])` is required before any older revisions can be requested. +A specific revision can be requested by revision sequence number or by exact timestamp, +as can its archive name. +Invoking `getHistory(true[, ...])` is required before any older revisions can be requested. ```php // get the latest 50 revisions @@ -299,7 +311,8 @@ $file = $wiki->getFile('Old-button.png'); $file->delete('The button was superseded by a new one'); ``` -To delete or revert to a specific older revision of the file, the archive name is needed: +To delete or revert to a specific older revision of the file, +the archive name is needed: ```php $file = $wiki->getFile('Often-changed-file.zip'); @@ -376,7 +389,9 @@ print_r($page->getError()); 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: +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