sarsoo/IF.Lastfm
1
0
Fork 0
mirror of https://github.com/Sarsoo/IF.Lastfm.git synced 2024-10-16 23:13:07 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated contributing.md (formatting and typo)

Browse Source 
Wrapped classes and methods names in backticks so that the generic types parameters show on github, and corrected a typo.
This commit is contained in:
Melvyn Laïly 2015-06-20 09:37:46 +02:00
parent 268afd59b8
commit d2fdbf1b10
1 changed files with 19 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/contributing.md
View File

@ -20,7 +20,7 @@ Choose one of [the issues marked "up for grabs"](https://github.com/inflatablefr
## Branching
In order to keep [the commit history](https://github.com/inflatablefriends/lastfm/commits/master) tidy, I might ```git squash``` commits from a PR before merging them in. This can cause problems with maintaining a fork: **if you send a PR from the master branch of your fork, then you will need to ```git pull --force``` after I merge in your changes**. To prevent this extra effort, you can either:
In order to keep [the commit history](https://github.com/inflatablefriends/lastfm/commits/master) tidy, I might `git squash` commits from a PR before merging them in. This can cause problems with maintaining a fork: **if you send a PR from the master branch of your fork, then you will need to `git pull --force` after I merge in your changes**. To prevent this extra effort, you can either:
1. Create a branch especially for your work, then send the PR from this branch. This means that any changes I make can never conflict with the master branch of your fork.
2. Squash your own commits before the PR is merged in.
@ -33,16 +33,16 @@ The API is structured according to [the command pattern](http://en.wikipedia.org
Once you have chosen an API method to work on, you need to do five things before submitting it for inclusion in the API:
1. Create the command in the right folder
2. Implement the command, deriving from GetAsyncCommandBase<T> or PostAsyncCommandBase<T> (depending on what [the documentation](http://www.last.fm/api) says)
3. Create a method on the relevent *Api class
2. Implement the command, deriving from `GetAsyncCommandBase<T>` or `PostAsyncCommandBase<T>` (depending on what [the documentation](http://www.last.fm/api) says)
3. Create a method on the relevant *Api class
4. Collect sample responses from the API for this method
5. Create a unit test class for the command using the sample responses
So if I wanted to work on the method ```track.getSimilar``` I would:
So if I wanted to work on the method `track.getSimilar` I would:
1. Create the [GetSimilarCommand](/src/IF.Lastfm.Core/Api/Commands/Track/GetSimilarCommand.cs) class in /src/IF.Lastfm.Core/Api/Commands/Track
2. Subclass GetAsyncCommandBase<T> because the documentation says the method does not need authentication. T will be a PageResponse<LastTrack> because the method returns a list of tracks.
3. Add a GetSimilar method on the TrackApi class
2. Subclass `GetAsyncCommandBase<T>` because the documentation says the method does not need authentication. T will be a `PageResponse<LastTrack>` because the method returns a list of tracks.
3. Add a `GetSimilar` method on the `TrackApi` class
4. Use the Syro dev tool to collect responses for: (page 0, limit 1), (page 0, limit 20) and a failure case, i.e. when a track which doesn't have similar responses. The failure case might be hard to find for some methods, when this is the case the test doesn't matter too much so you may skip it.
5. Create a class in the unit test project, and test the command execution with each of the sample responses.
@ -52,33 +52,33 @@ Once all your tests pass and the project builds, commit your work to your repo,
Every command should have a corresponding unit test file when it makes sense; you can use the type of command as an indicator for which tests are necessary. In addition to the below, any edge cases (such as the timestamps for an album being represented in ms or s depending on which endpoint is called) should be covered.
#### LastResponse
#### `LastResponse`
- ParametersCorrect() - test that command.SetParameters() generates the expected output. If the command has multiple constructors or optional parameters these should all be covered in the test.
- `ParametersCorrect()` - test that `command.SetParameters()` generates the expected output. If the command has multiple constructors or optional parameters these should all be covered in the test.
#### LastResponse<T>
#### `LastResponse<T>`
As LastResponse, plus
As `LastResponse`, plus
- HandleSuccess() - test that command.ExecuteAsync() deserialises a typical successful response for this API response into the correct type.
- HandleError() - test that command.ExecuteAsync() deserialises a typical error response for this API correctly, including method code and message.
- `HandleSuccess()` - test that `command.ExecuteAsync()` deserialises a typical successful response for this API response into the correct type.
- `HandleError()` - test that `command.ExecuteAsync()` deserialises a typical error response for this API correctly, including method code and message.
#### PageResponse<T>
#### `PageResponse<T>`
As LastResponse, plus
As `LastResponse`, plus
- HandleSuccessSingle() - test that command.ExecuteAsync() deserialises a typical successful response with a single item for this API response correctly: the API doesn't use JSON array notation for single items.
- HandleSuccessMultiple() - test that command.ExecuteAsync() deserialises a typical successful response with multiple items for this API response correctly. Set the limit parameter to 2 for easier test writing.
- HandleError() - test that command.ExecuteAsync() deserialises a typical error response for this API correctly, including method code and message.
- `HandleSuccessSingle()` - test that `command.ExecuteAsync()` deserialises a typical successful response with a single item for this API response correctly: the API doesn't use JSON array notation for single items.
- `HandleSuccessMultiple()` - test that `command.ExecuteAsync()` deserialises a typical successful response with multiple items for this API response correctly. Set the limit parameter to 2 for easier test writing.
- `HandleError()` - test that `command.ExecuteAsync()` deserialises a typical error response for this API correctly, including method code and message.
### Syro
IF.Lastfm.Syro is a tool to make building requests to the Last.fm JSON API easier, using the mechanisms in the core library for stuff like generating method signatures and authenticating.
`IF.Lastfm.Syro` is a tool to make building requests to the Last.fm JSON API easier, using the mechanisms in the core library for stuff like generating method signatures and authenticating.
Build the solution and then run the IF.Lastfm.Syro.exe in src/IF.Lastfm.Syro/bin/Debug.
[![Syro app](https://github.com/inflatablefriends/lastfm/blob/master/res/syro.png)](https://github.com/inflatablefriends/lastfm/blob/master/res/syro.png)
The three dropdown menus correspond to the type of the command you want to build - so track.getSimilar corresponds to DummyGetAsyncCommand, PageResponse and LastTrack. The rest of the page corresponds to parameters for that method - check the Last.fm API documentation for what needs to be sent and fill in the data grid.
The three dropdown menus correspond to the type of the command you want to build - so track.getSimilar corresponds to `DummyGetAsyncCommand`, `PageResponse` and `LastTrack`. The rest of the page corresponds to parameters for that method - check the Last.fm API documentation for what needs to be sent and fill in the data grid.
Clicking the execute button will build and execute the command, and then save the JSON response to a file in the /tmp directory of the solution.