Metadata-Version: 1.0
Name: github-collective
Version: 0.4
Summary: Script to manage GitHub organizations in a collective manner
Home-page: https://github.com/collective/github-collective
Author: Rok Garbas
Author-email: rok@garbas.si
License: BSD
Description: Introduction
        ============
        
        `GitHub organizations`_ are great way for organizations to manage their Git
        repositories. This tool will let you automate the tedious tasks of creating
        teams, granting permissions, and creating repositories or modifying their
        settings.
        
        The approach that the ``github-collective`` tool takes is that you edit a
        central configuration (currently an ini-like file) from where options are
        read and synchronized to GitHub respectively.
        
        Initially, the purpose of this script was to manage Plone's collective
        organization on GitHub: http://collective.github.com. It is currently in use
        in several other locations.
        
        
        .. contents
        
        Documentation
        =============
        
        Read the full documentation at http://github-collective.rtfd.org.
        
        Features
        ========
        
        * Create one central configuration that you can sync to GitHub to configure
          your organisation's settings, repositories, teams, and more.
        
          * Combine this with GitHub's fork-and-pull request model to easily
            allow non-administrative users to create and manage repositories
            with minimal overhead.
        
        * Repositories: create and modify repositories within an organization
        
          * Configure all repository properties as per the `GitHub Repos API`_,
            including privacy (public/private), description, and other metadata. 
          * After the initial repository creation happens, updated values in your
            configuration will replace those on GitHub.
        
        * Service hooks: add and modify service hooks for repositories.
        
          * GitHub repositories have support for sending information upon
            certain events taking place (for instance, pushes being made to a 
            repository or a fork being taken).
          * After the initial repo creation process takes place, updated values in your
            hook configuration will `replace` those on GitHub. 
          * Hooks not present in your configuration (such as those manually added
            on GitHub or those removed from local configuration) will *not* be
            deleted.
        
        * Teams: automatically create teams and modify members
        
          * Control permissions for teams (for example: push, pull or admin)
        
        * Automatically syncs all of the above with GitHub when the tool is run.
        
        * Buildout-style variable substitution in the form ``${section:option}``.
        
        
        .. _`GitHub organizations`: https://github.com/blog/674-introducing-organizations
        .. _`GitHub Repos API`: http://developer.github.com/v3/repos/#create
        
        
        
        Usage
        =====
        
        When ``github-collective`` is installed it should create an executable with
        same name in your `bin` directory. 
        ::
        
            % bin/github-collective --help
            usage: github-collective [-h] -c CONFIG [-M MAILER] [-C CACHE] -o GITHUB_ORG
                                     -u GITHUB_USERNAME -P GITHUB_PASSWORD [-v] [-p]
            
            This tool will let you automate tedious tasks of creating teams granting
            permission and creating repositories.
            
            optional arguments:
              -h, --help            show this help message and exit
              -c CONFIG, --config CONFIG
                                    path to configuration file (could also be remote
                                    location). eg.
                                    http://collective.github.com/permissions.cfg (default:
                                    None)
              -M MAILER, --mailer MAILER
                                    TODO (default: None)
              -C CACHE, --cache CACHE
                                    path to file where to cache results from github.
                                    (default: None)
              -o GITHUB_ORG, --github-org GITHUB_ORG
                                    github organisation. (default: None)
              -u GITHUB_USERNAME, --github-username GITHUB_USERNAME
                                    github account username. (default: None)
              -P GITHUB_PASSWORD, --github-password GITHUB_PASSWORD
                                    github account password. (default: None)
              -v, --verbose
              -p, --pretend
        
        Locally-stored configuration
        ----------------------------
        
        ::
        
            % bin/github-collective \
                -c example.cfg \ # path to configuration file
                -o vim-addons \  # organization that we are 
                -u garbas \      # account that has management right for organization
                -P PASSWORD      # account password
        
        Remotely-stored configuration (GitHub)
        --------------------------------------
        
        ::
        
            % bin/github-collective \
                -c https://raw.github.com/collective/github-collective/master/example.cfg \
                                 # url to configuration file
                -o collective \  # organization that we are 
                -u garbas \      # account that has management right for organization
                -P PASSWORD      # account password
        
        Cached configuration
        --------------------
        
        ::
        
            % bin/github-collective \
                -c https://raw.github.com/collective/github-collective/master/example.cfg \
                                 # url to configuration file
                -C .cache        # file where store and read cached results from github
                -o collective \  # organization that we are 
                -u garbas \      # account that has management right for organization
                -P PASSWORD      # account password
        
        
        Testing
        =======
        
        ``nose`` is utilised for testing and configuration for ``nose`` exists
        within the ``setup.cfg`` file within this project.  This configuration
        automatically examines files for tests within the project, including
        this read-me itself. You can initialise and run tests using the Buildout
        configuration provided::
        
            git clone git://github.com/collective/github-collective.git
            cd github-collective
            virtualenv .
            python boostrap.py
            bin/buildout
            bin/nosetests
        
        `tox <http://tox.testrun.org/latest/>`_ is used to ensure this package
        installs correctly under each version of Python.  Currently we test 
        Python 2.6 and Python 2.7.  Support for running tests under ``tox`` will
        come shortly. To test installation::
        
            git clone git://github.com/collective/github-collective.git
            cd github-collective
            virtualenv .
            pip install tox
            tox
            
        
        Issues and Contributing
        =======================
        
        Report issues via this project's GitHub issue tracker at
        https://github.com/collective/github-collective/issues.
        
        Contribute by submitting a pull request on GitHub or else by
        adding yourself to the `Collective <http://collective.github.com>`_
        and contributing directly.
        
        Todo
        ====
         
        - Allow configuration of organisation settings via API
        - Add facility to continue if error experienced
        - Send emails to owners about removing repos
        - Better logging mechanism (eg. logbook)
        - Support configuration extensibility (eg ``extends =`` syntax) for
          using multiple configuration files.
        
        
        Credits
        =======
        
        :Author: `Rok Garbas`_ (garbas)
        :Contributor: `David Beitey`_ (davidjb)
        
        .. _`Rok Garbas`: http://www.garbas.si
        .. _`David Beitey`: http://davidjb.com
        
        Changelog
        =========
        
        0.4 (2012-11-28)
        ----------------
        
        - Restore ability to fork repositories to organisations after unexpected
          API change.
          [davidjb]
        - Ensure fork data payload (org name) is sent as JSON.
          [davidjb]
        - Allow forks to be correctly named once created. GitHub's API forks using
          the same name originally, so we need to rename once forked.
          [davidjb]
        - Add rename helper functionality to sync module. (Note that configuration 
          does not yet support renaming)
          [davidjb]
        - Read the Docs-ified documentation.
          [davidjb]
        
        
        0.3.2 (2012-07-17)
        ------------------
        
        - Fix issue with templating of hook variables. Previously,
          the original config was being altered, preventing further
          templating.
          [davidjb]
        - Fix issue with hooks being updated from cache by storing the
          existing integer ID.
          [davidjb]
        - Fix issue with cache not being updated on repo change.
          [davidjb]
        
        
        0.3.1 (2012-07-17)
        ------------------
        
        - Only send API options to GitHub to reduce overhead.
          [davidjb]
        - Display output of changes to configuration when running in verbose 
          mode. This helps track down oddities with GitHub value storage to
          reduce overhead.
          [davidjb]
        
        
        0.3 (2012-07-17)
        ----------------
        
        - Implement Buildout-style variable substitution for configuration with
          doctesting. 
          [davidjb]
        - Output resolved configuration when running in verbose mode.
          [davidjb]
        - Implement deletion of repos from configuration now GitHub API v3 
          supports this. *Warning*: if a repo exists on GitHub but not in 
          your configuration, it will now be deleted. Run the command in
          `pretend` mode first if unsure.
          [davidjb]
        - Optimise deletion process to not clear cache when attempting to 
          delete.
          [davidjb]
        - Add extras_require option for testing to use ``nose``.
          [davidjb]
        - Updating to depend on ``requests==0.13.1``.
          [davidjb] 
        
        
        0.2 (2012-06-22)
        ----------------
        
        - Allow service hooks to be specified within the configuration.
          For samples, see the example configuration. Any GitHub supported
          hook can be associated with repos.
          [davidjb]
        - Allowing repo properties to be set on creation and editing of config.
          For available options, see http://developer.github.com/v3/repos/#create.
          This facilities private repo creation (if quota available), amongst other
          options.
          [davidjb]
        - Fix response parsing issue when creating teams.
          [davidjb]
        - Improved end-user documentation.
          [davidjb]
        
        0.1.4 - 2012-02-19
        ------------------
        
        - adding support for requests==0.10.2 and removing pdb
          [`f561d79`_, garbas]
        
        0.1.3 - 2011-07-09
        ------------------
        
        - fix caching file bug, cache now working
          [garbas]
        
        0.1.2 - 2011-07-03
        ------------------
        
        - remane team to old_team to keep convention in sync.run method, using
          add instead of update on sets
          [`e48de49`_, garbas]
        - pretend should work for all except get reuqest type
          [`e098f9d`_, garbas]
        - nicer dump of json in cache file, unindent section which searches for
          repos defined in teams
          [`b8cb123`_, garbas]
        - we should write to cache file when there is no cache file avaliable
          [`fd7f9ee`_, garbas]
        
        0.1.1 - 2011-07-02
        ------------------
        
        - and we have first bugfix relese, after refractoring and merging
          ``enable-cache`` branch.
          [`a09d174`_, garbas]
        
        
        0.1 - 2011-07-02
        ----------------
        
        - initial release
          [garbas]
        
        .. _`f561d79`: https://github.com/garbas/github-collective/commit/f561d79
        .. _`e48de49`: https://github.com/garbas/github-collective/commit/e48de49
        .. _`e098f9d`: https://github.com/garbas/github-collective/commit/e098f9d
        .. _`b8cb123`: https://github.com/garbas/github-collective/commit/b8cb123
        .. _`fd7f9ee`: https://github.com/garbas/github-collective/commit/fd7f9ee
        .. _`a09d174`: https://github.com/garbas/github-collective/commit/a09d174
        
Keywords: github git permission collaboration collective organization
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
