Skip to content

Create CONTRIBUTING.md file #135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Xymph merged 2 commits into from
Aug 31, 2021
Merged

Create CONTRIBUTING.md file #135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f946925
Add CONTRIBUTING.md file
waldyrious Aug 29, 2021
656e027
Format markdown files to break long lines
waldyrious Aug 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 26 additions & 13 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,13 @@ 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

* 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:_
Expand All @@ -36,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

Expand All @@ -57,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

Expand All @@ -69,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

Expand All @@ -84,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
Expand Down Expand Up @@ -133,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
Expand Down Expand Up @@ -191,3 +203,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
30 changes: 30 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
35 changes: 15 additions & 20 deletions GOVERNANCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,38 +4,32 @@ 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.
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
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,
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:

Expand All @@ -49,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.
18 changes: 12 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,23 @@ 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.
Comment thread
Xymph marked this conversation as resolved.
It requires MediaWiki v1.27 or newer.
See [CHANGELOG.md](CHANGELOG.md) for the detailed version history.

## Installation

**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:
Expand Down Expand Up @@ -67,6 +68,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.
Expand Down
37 changes: 26 additions & 11 deletions USAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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...

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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();
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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');
Expand Down Expand Up @@ -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
Expand Down