LAST UPDATE: 2018-10-04
The goal of this project is to enhance the code quality from its pre-fork condition and make contributing to this project easier and more developer friendly to allow for further development and improvements.
A secondary goal is to strive to exercise the best software development practices. While creating a good, high quality product is important to us, we think the journey is where 95% of the fun lies. We're approaching this project as professionally as our present skills allow with an aim in mind to improve them. We're not here to provide all the answers and we make no claims on having them. If you have recommendations for improving the project, we definitely welcome them and an opportunity to learn from you. We have no product deadline here and we are happier doing things well and right instead of as fast as we can. This is a project for stopping and smelling the software roses.
This module was recently forked from
Moo::Google on 2018-10-03. The
Moo::Google project stalled sometime in January 2018 during the middle of
renaming the module to WebService::Google::Client. The fork has successfully
completed renaming the module and is available on metacpan for
download for download
and installation using traditional Perl installer programs (cpan and cpanm).
This module is currently undergoing an overhaul in an attempt to make it easier for contributors to chip in and help improve the quality and functionality of the module. While functional and bug-free, the module has some large gaps in its API coverage which are in the process of getting documented. These gaps can be overcome by lower-level API calls for now so the module can still be used but some Google API calls will take a little more effort to code.
Once the overhaul is complete, work will begin on a second phase to overhaul the code as necessary and enhance its ability to make API calls using a higher level interface.
Though the module uses Dist::Zilla to automate the build generation and
release process. Dist::Zilla has a reputation for being difficult to learn and
a pain to work with. The truth is, though, that most contributors don't even
need to know much about it and you don't even need to have it installed to
contribute to this project. There are some simple things to be aware of,
however. See the section on Working with Dist::Zilla below for more
information. The bottom line is, don't let Dist::Zilla dissuade you from
contributing.
All bugs should be reported via this module's GitHub home page. Bug reports and questions will be responded to quickly and courteously to the best of our ability. Please be as considerate and thorough in your posts as possible. And we like asking really dumb questions as well as answering them, so don't be shy.
For now, there is only one maintainer of the main GitHub repo. Therefore, if you wish to make code contributions, you should fork the project on GitHub and make pull requests from the fork.
If your contribution is small and obvious, feel free to push directly to the
devel branch of this repository if you don't have your own branch on this
repository. Examples of "small and obvious" contributions include:
- Fixing typos, spelling and grammar mistakes
- Obvious bug fixes
- Small enhancements to improve code quality, no more than 1 to 10 lines and all in the same function. These enhancements should not change the behavior of the module in any significant way.
- Fixes for existing, failed tests that don't require new functions to be written.
- Relatively minor documentation additions, not more than a paragraph or two.
- If it requires a new test get written, it is not a small contribution. See the next section below on that.
If in doubt over whether your proposed contribution is "small" or not, feel free to open an issue to discuss.
If you have an idea for a new feature for a way to vastly improve this module, we are all ears. But we want to understand what you intend to do before you go forward and we definitely don't want you spinning your wheels. So we ask that you please consult with the developer so there is agreement on the scope of the contribution, a rough game plan for accomplishing it and the tests that will be needed.
Once that's done, we will then create a new branch for you. Once the branch is created, you should create a new branch in your fork and set it the branch in this repo that was set up for you as the upstream branch for your new local branch. If you need help with this, feel free to ask. We will have a procedure for this once we test it and make sure it works well and is easy.
If you are making a lot of small commits, please don't pile up a bunch of unrelated commits after another in a single pull request. Instead, set up a separate branch for each group of related commits. Branching is easy:
git co -b <new_branch_name>
Then you can go to work on the related commits on that branch. Then do a pull request for that branch.
We know everyone has a preferred way for using Git. But please respect the git work flow we have chosen for this project. We realize this isn't a huge project. But part of the reason we have chosen this work flow is to help get more comfortable with using git on more complicated projects. We are open for ways to make things simpler, but we aren't willing to change the entire work flow we have established which was chose for a reason: learning. Please don't take offense and we greatly appreciate your patience even if you think we're being slightly (or really) ridiculous.
Much of what was said in last section applies to this one as well. Yes, it may seem like a bit of overkill for a project like this, but before any code for a new feature or bug fix is released, we'd like to see a test for it first. Again, we are using this project to help form good coding habits and help cut our teeth practicing them. Thanks for your understanding.
This is a short list of stuff not to do or worry about:
- DO NOT make edits directly to README.md file. This file is generated automatically from the inline POD. So any changes you want to make should go to POD.
- DO NOT edit the
dist.iniconfiguration file. - DO NOT edit the
weaver.iniconfiguration files. - DO NOT change the
our $VERSIONcode in any of the module files. These are all automated.
OK, that's it as far as the "do nots" go. Only other thing you should know is
how to run tests with Dist::Zilla (if you have Dist::Zilla installed). Read
the next section for more on this.
If you are new to testing, we offer this basic guide to help you which will hopefully provide you with enough information or at least phrases for searching the web for more details. If you are familiar with testing, you will want to read the "Getting Access Tokens to Tests" section.
To run tests, clone the WebService::Google::Client repository to your local
machine with Perl installed. Run your tests from inside the repository with the
prove command and the -l option ("l" for library). Example commands:
Run the tests inside of single test file:
prove -l t/client_tests.t
Run all the tests in a directory recursively:
prove -lr t
See the prove documentation for more options and examples.
There are two types of tests, standard tests and extra tests. Extra tests are also frequently synonymous with author tests, the term we will use here.
Standard tests, located in the t directory of this distribution, are run by
end users to make sure Web::Service::Client is installed properly and that it
can run on their hardware and software configuration. They are also used by
developers to ensure the code works properly.
Author tests, located in the xt directory, are run only by developers. Any
test that requires an actual API call must go in the author tests directory.
These tests will fail for end users since users will cannot be run by end users
because end users will not have the config.json which contains the access
tokens it is important not to place such tests in the t directory for
standard tests.
Running author tests will require that you generate a config.json file per
the instructions above in the "GETTING STARTED" section. This config.json
file contains the access tokens the module needs to make the requests. You will
also need to set two environment variables in your bash configuration file like
so:
export GOOGLE_TOKENSFILE="/path/to/config.json"
export GMAIL_FOR_TESTING="your_address@gmail.com"
Be sure to source (reload) your bash configuration file before running the tests. You'll have to research how to set these variables yourself. Please submit a patch to this project to help document this.
All tests should be run before committing your patch for all but minor
documentation changes and other non-code improvements. If you have
Dist::Zilla installed, you can do:
dzil test
This will run all standard and author tests. If you want to run just standard tests, do:
dzil test --no-author