diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..05d9ff5c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing + +## Issues + +A good issue includes a [short, self contained, correct example](http://sscce.org/) of the problem, something like: + +```python +assert github.Github().get_user("jacquev6").name == "Vincent Jacques" +``` + +It is even better if you provide the debug logs associated with your issue. +Enable them with `github.enable_console_debug_logging` and copy them in the body of the issue. +**Warning:** you may want to remove some private information (authentication information is removed, but there may be private stuff in the messages) + +If for any reason you are not able to do that, open your issue anyway and a maintainer will see what is needed to solve your problem. + +## Pull Requests + +Pull Requests should attempt clearly the problem they attempt to solve and how the author went about solving the problem. +Ideally, changes should be made in logical commits and add tests to improve the project's coverage of the GitHub API. + +## Automated tests + +You can run the tests through `python -m github.tests`. +Run a specific test with `python -m github.tests TestCase` or `python -m github.tests TestCase.testMethod`. + +If you add a new test, for example `Issue139.testCompletion`, you must add an import in `github/tests/AllTests.py`. +Then, you have to run `python -m github.tests Issue139.testCompletion --record` to create the `github/tests/ReplayData/*.txt` files needed for you new test. +Check them and commit them as well. +You will need a `GithubCredentials.py` file at the root of the project with the following contents: + +``` +login = "my_login" +password = "my_password" +oauth_token = "my_token" # Can be left empty if not used +``` + +If you use 2 factor authentication on your Github account, tests that require a login/password authentication will fail. +You can use `python -m github.tests Issue139.testCompletion --record --auth_with_token` to use the `oauth_token` field specified in `GitHubCredentials.py` when recording a unit test interaction. + +## Coding conventions + +PyGithub follows [pep8 Style Guide for Python Code](http://www.python.org/dev/peps/pep-0008/) except for line length. +Please check your code with [pep8 Python style guide checker](http://pypi.python.org/pypi/pep8), by running `pep8 --ignore=E501 github`. diff --git a/Contributing.rst b/Contributing.rst deleted file mode 100644 index 56c7044d..00000000 --- a/Contributing.rst +++ /dev/null @@ -1,39 +0,0 @@ -Contributing -============ - -Issues ------- - -A good issue includes a `short, self contained, correct example `_ of the problem, something like:: - - assert github.Github().get_user("jacquev6").name == "Vincent Jacques" - -It is even better if you provide the debug logs associated with your issue. -Enable them with :func:`github.enable_console_debug_logging` and copy them in the body of the issue. -Warning, you may want to remove some private information (authentication information is removed, but there may be private stuff in the messages) - -If for any reason you are not able to do that, open your issue anyway and we will see what is needed to solve your problem. - -Pull requests -------------- - -Please do your pull requests on the ``develop`` branch. - -Automated tests -~~~~~~~~~~~~~~~ - -You can run the tests through ``python -m github.tests``. Run a specific test with ``python -m github.tests TestCase`` or ``python -m github.tests TestCase.testMethod``. - -If you add a new test, for example ``Issue139.testCompletion``, you must add an import in ``github/tests/AllTests.py``. Then, you have to run ``python -m github.tests Issue139.testCompletion --record`` to create the ``github/tests/ReplayData/*.txt`` files needed for you new test. Check them and commit them as well. You will need a ``GithubCredentials.py`` file at the root of the project with the following contents:: - - login = "my_login" - password = "my_password" - oauth_token = "my_token" # Can be left empty if not used - -If you use 2 factor authentication on your Github account, tests that require a login/password authentication will fail. You can use ``python -m github.tests Issue139.testCompletion --record --auth_with_token`` to use the oauth_token when recording a unit test interaction. - -Coding conventions -~~~~~~~~~~~~~~~~~~ - -PyGithub follows `pep8 Style Guide for Python Code `_ except for line length. -Please check your code with `pep8 Python style guide checker `_, by running ``pep8 --ignore=E501 github``. diff --git a/MAINTAINERS b/MAINTAINERS index 546c3c4c..f8cbd3bb 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1,3 +1,4 @@ -jacquev6 -jzelinskie -nhomar +Adam Dangoor (@adamtheturtle) +Jimmy Zelinskie (@jzelinskie) +Nhomar Hernández (@nhomar) +Vincent Jacques (@jacquev6) diff --git a/MANIFEST.in b/MANIFEST.in index 94210101..50185953 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,2 @@ include COPYING* -include README.rst +include README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..ae065a7b --- /dev/null +++ b/README.md @@ -0,0 +1,42 @@ +# PyGitHub + +[![Build Status](https://travis-ci.org/PyGithub/PyGithub.svg?branch=master)](https://travis-ci.org/PyGithub/PyGithub) +[![PyPi](https://img.shields.io/pypi/dm/pygithub.svg)](https://pypi.python.org/pypi?%3Aaction=search&term=pygithub&submit=search) +[![readthedocs](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://pygithub.readthedocs.org/en/stable) +[![License](https://img.shields.io/badge/license-LGPL-blue.svg)](https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License) + +PyGitHub is a Python (2 and 3) library to access the [GitHub API v3]. +This library enables you to manage [GitHub] resources such as repositories, user profiles, and organizations in your Python applications. + +[GitHub API v3]: https://developer.github.com/v3 +[GitHub]: https://github.com + +## Simple Demo + +```python +from github import Github + +# First create a Github instance: +g = Github("user", "password") + +# Then play with your Github objects: +for repo in g.get_user().get_repos(): + print repo.name + repo.edit(has_wiki=False) +``` + +## Development + +### Contributing + +Long-term discussion and bug reports are maintained via GitHub Issues. +Code review is done via GitHub Pull Requests. + +For more information read [CONTRIBUTING.md]. + +[CONTRIBUTING.md]: /CONTRIBUTING.md + +### Maintainership + +We're actively seeking maintainers that will triage issues and pull requests and cut releases. +If you work on a project that leverages PyGitHub and have a vested interest in keeping the code alive and well, send an email to someone in the MAINTAINERS file. diff --git a/README.rst b/README.rst deleted file mode 100644 index fbbd7887..00000000 --- a/README.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. image:: https://travis-ci.org/PyGithub/PyGithub.svg?branch=master - :target: https://travis-ci.org/PyGithub/PyGithub - -This is a Python (2 and 3) library to access the `Github API v3 `_. -With it, you can manage `Github `_ resources (repositories, user profiles, organizations, etc.) from Python scripts. - -It covers almost the full API (see "What's missing" below), and all methods are tested against the real Github site. - -Should you have any question, any remark, or if you find a bug, or if there is something you can do with the API but not with PyGithub, please `open an issue `_. - -For further details, please refer to the `reference documentation `_ at ``readthedocs.org``. - -Looking for maintainers -============================================= - -As of February 2015, the original author, jacquev6, is unable to devote much time to maintaining the project. -If you are using the project at work and have a vested interest in keeping the code healthy, shoot him an email. - -What's new? -=========== - -Version 1.26.0 (November 5th, 2015) ------------------------------------ - -* Added context parameter to Status API -* Changed InputGitAuthor to reflect that time is an optional parameter -* Added sort option to get_pulls -* Added api_preview parameter to Requester class -* Return empty list instead of None for pagination with no pages -* Removed URL scheme validation that broke GitHub Enterprise -* Added "add_membership" call to Teams -* Added support to lazily load repositories -* Updated test suite to record with oauth tokens -* Added support for http_proxy -* Add support for filter/role options in Organization.get_members() -* Changed Organization.get_members's filter parameter to _filter -* Fix escaping so that labels now support whitespaces -* Updated create_issue to support taking a list of strings for labels -* Added support for long integers in get_repo -* Fixed pagination to thread headers between requests -* Added repo.get_stargazers_with_dates() - -Version 1.25.2 (October 7th, 2014) ----------------------------------- - -* `Work around `__ the API v3 returning ``null`` in some paginated responses, thanks `erichaase `__ for the bug report - -Version 1.25.1 (September 28th, 2014) -------------------------------------- - -* `Fix `__ two-factor authentication header, thanks to `tradej `__ for the pull request - -`Version 1.25.0 `_ (May 4th, 2014) ---------------------------------------------------------------------------------------------------------- - -* `Implement `__ getting repos by id, thanks to `tylertreat `__ for the pull request -* `Add `__ ``Gist.owner``, thanks to `dalejung `__ for the pull request - -What's missing? Github API v3 URLs not covered by PyGithub -========================================================== - -A lot of things including the following URLs, and every new things published by GitHub recently. - -* ``/applications/:client_id/tokens/:access_token`` (GET) -* ``/authorizations/clients/:client_id`` (PUT) -* ``/feeds`` (GET) -* ``/meta`` (GET) -* ``/notifications`` (PUT) -* ``/notifications/emails`` (GET) -* ``/notifications/emails`` (PATCH) -* ``/notifications/global/emails`` (GET) -* ``/notifications/global/emails`` (PUT) -* ``/notifications/organization/:org/emails`` (GET) -* ``/notifications/organization/:org/emails`` (PUT) -* ``/notifications/settings`` (GET) -* ``/notifications/settings`` (PATCH) -* ``/notifications/threads/:id`` (PATCH) -* ``/notifications/threads/:id/subscription`` (DELETE) -* ``/notifications/threads/:id/subscription`` (GET) -* ``/notifications/threads/:id/subscription`` (PUT) -* ``/repos/:owner/:repo/contents/:path`` (DELETE) -* ``/repos/:owner/:repo/contents/:path`` (PUT) -* ``/repos/:owner/:repo/notifications`` (GET) -* ``/repos/:owner/:repo/notifications`` (PUT) -* ``/repos/:owner/:repo/releases/:id/assets`` (GET) -* ``/repos/:owner/:repo/releases/assets/:id`` (DELETE) -* ``/repos/:owner/:repo/releases/assets/:id`` (GET) -* ``/repos/:owner/:repo/releases/assets/:id`` (PATCH) -* ``/repos/:owner/:repo/subscription`` (DELETE) -* ``/repos/:owner/:repo/subscription`` (GET) -* ``/repos/:owner/:repo/subscription`` (PUT)