Skip to content

Commit 0ea7f42

Browse files
strzibnystrzibny
authored
Merge pull request #20 from strzibny/development-guide
Separate development guide from README
2 parents 96b8aaf + 1194b14 commit 0ea7f42

File tree

3 files changed

+88
-260
lines changed

3 files changed

+88
-260
lines changed

‎CONTRIBUTING.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Contributing
2+
3+
## Key goals
4+
5+
- Brand centric instead of search engine based
6+
- No hard-coded logic per search engine
7+
- Simple HTTP client (lightweight, reduced dependency)
8+
- No magic default values
9+
- Thread safe
10+
- Easy extension
11+
- Defensive code style (raise a custom exception)
12+
- TDD - Test driven development
13+
- Best API coding practice per platform
14+
- KiSS principles
15+
16+
## Inspirations
17+
18+
This project source code and coding style was inspired by the most awesome Ruby Gems:
19+
- [bcrypt](https://github.com/bcrypt-ruby/bcrypt-ruby)
20+
- [Nokogiri](https://nokogiri.org)
21+
- [Cloudfare](https://rubygems.org/gems/cloudflare/versions/2.1.0)
22+
- [rest-client](https://rubygems.org/gems/rest-client)
23+
- [stripe](https://rubygems.org/gems/stripe)
24+
25+
## Code quality expectations
26+
27+
- 0 lint offense: `rake lint`
28+
- 100% tests passing: `rake test`
29+
- 100% code coverage: `rake coverage` (simple-cov)
30+
31+
## Continuous integration
32+
33+
We love [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) and [Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD) at SerpApi.
34+
We use RSpec and Github Actions to test our infrastructure around the clock, and that includes all changes to our clients.
35+
36+
The directory spec/ includes specification which serves the dual purposes of examples and functional tests.
37+
38+
Set your secret API key in your shell before running a test.
39+
The SerpApi key can be obtained from [serpapi.com/signup](https://serpapi.com/users/sign_up?plan=free).
40+
```bash
41+
export SERPAPI_KEY="your_secret_key"
42+
```
43+
Install testing dependency
44+
```bash
45+
$ bundle install
46+
# or
47+
$ rake dependency
48+
```
49+
50+
Check code quality using Lint.
51+
```bash
52+
$ rake lint
53+
```
54+
55+
Run basic test
56+
```bash
57+
$ rake test
58+
```
59+
60+
Run tests with code coverage
61+
```bash
62+
$ rake coverage
63+
```
64+
65+
Review coverage report generated by `rake coverage`
66+
```sh
67+
# Current coverage: 98.68% (75 / 76 lines)
68+
open coverage/index.html
69+
```
70+
71+
Review documentation generated by `rake doc`
72+
```sh
73+
open doc/index.html
74+
```
75+
76+
Run full regression test suite on the examples.
77+
```bash
78+
rake regression
79+
```
80+
81+
Test the actuall packaged gem locally using the demo scripts.
82+
```bash
83+
$ rake oobt
84+
```
85+
86+
Open ./Rakefile for more information.

‎README.md‎

Lines changed: 2 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1097,133 +1097,6 @@ Most notable improvements:
10971097

10981098
Ruby 2.7 and higher is supported.
10991099

1100-
## Developer Guide
1101-
### Key goals
1102-
- Brand centric instead of search engine based
1103-
- No hard-coded logic per search engine
1104-
- Simple HTTP client (lightweight, reduced dependency)
1105-
- No magic default values
1106-
- Thread safe
1107-
- Easy extension
1108-
- Defensive code style (raise a custom exception)
1109-
- TDD - Test driven development
1110-
- Best API coding practice per platform
1111-
- KiSS principles
1112-
1113-
### Inspirations
1114-
This project source code and coding style was inspired by the most awesome Ruby Gems:
1115-
- [bcrypt](https://github.com/bcrypt-ruby/bcrypt-ruby)
1116-
- [Nokogiri](https://nokogiri.org)
1117-
- [Cloudfare](https://rubygems.org/gems/cloudflare/versions/2.1.0)
1118-
- [rest-client](https://rubygems.org/gems/rest-client)
1119-
- [stripe](https://rubygems.org/gems/stripe)
1120-
1121-
### Code quality expectations
1122-
- 0 lint offense: `rake lint`
1123-
- 100% tests passing: `rake test`
1124-
- 100% code coverage: `rake coverage` (simple-cov)
1125-
1126-
# Developer Guide
1127-
## Design : UML diagram
1128-
### Class diagram
1129-
```mermaid
1130-
classDiagram
1131-
Application *-- serpapi
1132-
serpapi *-- Client
1133-
class Client {
1134-
engine String
1135-
api_key String
1136-
params Hash
1137-
search() Hash
1138-
html() String
1139-
location() String
1140-
search_archive() Hash
1141-
account() Hash
1142-
}
1143-
openuri <.. Client
1144-
json <.. Client
1145-
Ruby <.. openuri
1146-
Ruby <.. json
1147-
```
1148-
### search() : Sequence diagram
1149-
```mermaid
1150-
sequenceDiagram
1151-
Client->>SerpApi.com: search() : http request
1152-
SerpApi.com-->>SerpApi.com: query search engine
1153-
SerpApi.com-->>SerpApi.com: parse HTML into JSON
1154-
SerpApi.com-->>Client: JSON string payload
1155-
Client-->>Client: decode JSON into Hash
1156-
```
1157-
where:
1158-
- The end user implements the application.
1159-
- Client refers to SerpApi:Client.
1160-
- SerpApi.com is the backend HTTP / REST service.
1161-
- Engine refers to Google, Baidu, Bing, and more.
1162-
1163-
The SerpApi.com service (backend)
1164-
- executes a scalable search on `engine: "google"` using the search query: `q: "coffee"`.
1165-
- parses the messy HTML responses from Google on the backend.
1166-
- returns a standardized JSON response.
1167-
The class SerpApi::Client (client side / ruby):
1168-
- Format the request to SerpApi.com server.
1169-
- Execute HTTP Get request.
1170-
- Parse JSON into Ruby Hash using a standard JSON library.
1171-
Et voila!
1172-
1173-
## Continuous integration
1174-
We love [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) and [Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD) at SerpApi.
1175-
We use RSpec and Github Actions to test our infrastructure around the clock, and that includes all changes to our clients.
1176-
1177-
The directory spec/ includes specification which serves the dual purposes of examples and functional tests.
1178-
1179-
Set your secret API key in your shell before running a test.
1180-
The SerpApi key can be obtained from [serpapi.com/signup](https://serpapi.com/users/sign_up?plan=free).
1181-
```bash
1182-
export SERPAPI_KEY="your_secret_key"
1183-
```
1184-
Install testing dependency
1185-
```bash
1186-
$ bundle install
1187-
# or
1188-
$ rake dependency
1189-
```
1190-
1191-
Check code quality using Lint.
1192-
```bash
1193-
$ rake lint
1194-
```
1195-
1196-
Run basic test
1197-
```bash
1198-
$ rake test
1199-
```
1200-
1201-
Run tests with code coverage
1202-
```bash
1203-
$ rake coverage
1204-
```
1205-
1206-
Review coverage report generated by `rake coverage`
1207-
```sh
1208-
# Current coverage: 98.68% (75 / 76 lines)
1209-
open coverage/index.html
1210-
```
1211-
1212-
Review documentation generated by `rake doc`
1213-
```sh
1214-
open doc/index.html
1215-
```
1216-
1217-
Run full regression test suite on the examples.
1218-
```bash
1219-
rake regression
1220-
```
1221-
1222-
Test the actuall packaged gem locally using the demo scripts.
1223-
```bash
1224-
$ rake oobt
1225-
```
1226-
1227-
Open ./Rakefile for more information.
1100+
## Contributing
12281101

1229-
Contributions are welcome. Feel free to submit a pull request!
1102+
Contributions are welcome. Make sure to read our [contributing guide](./CONTRIBUTING.md).

‎README.md.erb‎

Lines changed: 0 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -582,134 +582,3 @@ Ruby 2.7 and higher is supported.
582582
* [2025-11-17] 1.0.2 Implement `inspect` functions for client
583583
* [2025-07-18] 1.0.1 Add support for old Ruby versions (2.7, 3.0)
584584
* [2025-07-01] 1.0.0 Full API support
585-
586-
## Developer Guide
587-
### Key goals
588-
- Brand centric instead of search engine based
589-
- No hard-coded logic per search engine
590-
- Simple HTTP client (lightweight, reduced dependency)
591-
- No magic default values
592-
- Thread safe
593-
- Easy extension
594-
- Defensive code style (raise a custom exception)
595-
- TDD - Test driven development
596-
- Best API coding practice per platform
597-
- KiSS principles
598-
599-
### Inspirations
600-
This project source code and coding style was inspired by the most awesome Ruby Gems:
601-
- [bcrypt](https://github.com/bcrypt-ruby/bcrypt-ruby)
602-
- [Nokogiri](https://nokogiri.org)
603-
- [Cloudfare](https://rubygems.org/gems/cloudflare/versions/2.1.0)
604-
- [rest-client](https://rubygems.org/gems/rest-client)
605-
- [stripe](https://rubygems.org/gems/stripe)
606-
607-
### Code quality expectations
608-
- 0 lint offense: `rake lint`
609-
- 100% tests passing: `rake test`
610-
- 100% code coverage: `rake coverage` (simple-cov)
611-
612-
# Developer Guide
613-
## Design : UML diagram
614-
### Class diagram
615-
```mermaid
616-
classDiagram
617-
Application *-- serpapi
618-
serpapi *-- Client
619-
class Client {
620-
engine String
621-
api_key String
622-
params Hash
623-
search() Hash
624-
html() String
625-
location() String
626-
search_archive() Hash
627-
account() Hash
628-
}
629-
openuri <.. Client
630-
json <.. Client
631-
Ruby <.. openuri
632-
Ruby <.. json
633-
```
634-
### search() : Sequence diagram
635-
```mermaid
636-
sequenceDiagram
637-
Client->>SerpApi.com: search() : http request
638-
SerpApi.com-->>SerpApi.com: query search engine
639-
SerpApi.com-->>SerpApi.com: parse HTML into JSON
640-
SerpApi.com-->>Client: JSON string payload
641-
Client-->>Client: decode JSON into Hash
642-
```
643-
where:
644-
- The end user implements the application.
645-
- Client refers to SerpApi:Client.
646-
- SerpApi.com is the backend HTTP / REST service.
647-
- Engine refers to Google, Baidu, Bing, and more.
648-
649-
The SerpApi.com service (backend)
650-
- executes a scalable search on `engine: "google"` using the search query: `q: "coffee"`.
651-
- parses the messy HTML responses from Google on the backend.
652-
- returns a standardized JSON response.
653-
The class SerpApi::Client (client side / ruby):
654-
- Format the request to SerpApi.com server.
655-
- Execute HTTP Get request.
656-
- Parse JSON into Ruby Hash using a standard JSON library.
657-
Et voila!
658-
659-
## Continuous integration
660-
We love [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) and [Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD) at SerpApi.
661-
We use RSpec and Github Actions to test our infrastructure around the clock, and that includes all changes to our clients.
662-
663-
The directory spec/ includes specification which serves the dual purposes of examples and functional tests.
664-
665-
Set your secret API key in your shell before running a test.
666-
The SerpApi key can be obtained from [serpapi.com/signup](https://serpapi.com/users/sign_up?plan=free).
667-
```bash
668-
export SERPAPI_KEY="your_secret_key"
669-
```
670-
Install testing dependency
671-
```bash
672-
$ bundle install
673-
# or
674-
$ rake dependency
675-
```
676-
677-
Check code quality using Lint.
678-
```bash
679-
$ rake lint
680-
```
681-
682-
Run basic test
683-
```bash
684-
$ rake test
685-
```
686-
687-
Run tests with code coverage
688-
```bash
689-
$ rake coverage
690-
```
691-
692-
Review coverage report generated by `rake coverage`
693-
```sh
694-
# Current coverage: 98.68% (75 / 76 lines)
695-
open coverage/index.html
696-
```
697-
698-
Review documentation generated by `rake doc`
699-
```sh
700-
open doc/index.html
701-
```
702-
703-
Run full regression test suite on the examples.
704-
```bash
705-
rake regression
706-
```
707-
708-
Test the actuall packaged gem locally using the demo scripts.
709-
```bash
710-
$ rake oobt
711-
```
712-
713-
Open ./Rakefile for more information.
714-
715-
Contributions are welcome. Feel free to submit a pull request!

0 commit comments

Comments
 (0)