Application to display git repo deploy cycle
requirements.txt file lists the requirements
for the Porchlight API and Django project. These are:
- Django 1.7
- Django Rest Framework
- Python Markdown (Used for formatting Django Rest Framework API documentation)
- mock (Used for testing)
To run the Porchlight API and Django project in your favorite
which creates isolated Python environments, is recommended.
virtualenv for Porchlight and "activate" it:
$ virtualenv porchlight_venv $ source porchlight_venv/bin/activate
Clone the Porchlight source code from Github:
$ git clone https://github.com/cfpb/porchlight
Install Porchlight's Python dependencies:
$ cd porchlight $ pip install -r requirements.txt
Initialize the Porchlight database.
(Note: SQLite is currently configured in Porchlight's
settings.py; this will probably be moved to a
local_settings.py file in the future which will needed to be editted. For now, if you want to use a different database, you'll need to edit
$ python manage.py migrate $ python manage.py runserver
Once that is done, you should be able to visit http://localhost:8000/admin, login, and begin creating Repository objects for which data can be collected.
To browse the REST API, you can visit http://localhost:8000/porchlight.
The Porchlight API Django app has three configuration options that define possible Python callables that can provide source data and value calculations for Porchlight.
PORCHLIGHT_UNDEPLOYED_SOURCES = ( ('porchlightapi.sources.random_undeployed_source', 'Random Undeployed Source'), ) PORCHLIGHT_DEPLOYED_SOURCES = ( ('porchlightapi.sources.random_undeployed_source', 'Random deployed Source'), )
Source callables for undeployed and deployed values. This is the list of possible data sources that is exposed to users who are adding repositories to Porchlight for data collection.
Value sources are described in more detail below.
PORCHLIGHT_VALUE_CALCULATOR = ( ('porchlightapi.sources.difference_value_calculator', 'Difference Between Undeployed and Deployed Value'), ('porchlightapi.sources.undeployed_value_only_calculator', 'Undeployed Value Only'), )
Value calculator callables for undeployed and deployed values. This is the list of possible value calculators that is exposed to users who are adding repositories to Porchlight.
Value calculators are described in more detail below.
The Porchlight API exposes two endpoints:
Returns a list of all available repositories in Porchlight.
url fields can all be searched using
?search=. For example,
?search=porc will match Porchlight.
Ordering can be changed based on
?ordering=. For example,
?ordering=name will order by name,
alphabetically. The ordering can be reversed using
Returns a list of available value data points in Porchlight.
The data points can be searched based on their associated
?search=porc would return a list of all data points
associated with the Porchlight repository.
Data points are always ordered descending by the date the data point was created.
Data points are also paginated, defaulting to 10 results (at the
moment). This can be modified using
?limit=, for example
?limit=5 will limit to five results. Pages subsequent to first
page can be selected using
?page=, for example
?page=2 will get
the second page of results.
Acquiring and Calculating Value
In order to collect data about repositories, Porchlight offers the
ability to plug in Python callables (classes implementing
functions) that acquire value data, and calculators that take
undeployed value data, deployed value data, and calculates the diffrence
getvalues Management Command
The Porchlight API includes a management command to pull data from the
configured sources for specified repositories or all repositories. This
command is suitable for
cron or similar periodic task systems.
For all repositories:
$ python manage.py getvalues ... Got datapoint for https://github.com/cfpb/porchlight: 398 ...
For a specific repository:
$ python manage.py getvalues Got datapoint for https://github.com/cfpb/porchlight: 398
A value source is a Python callable that takes a project url (the primary means by which Porchlight repositories are identified) and returns a three-tuple that includes:
(value identifier, value datetime, value)
The value identifier is a string that would corrospond to, for example, a Git SHA for a specific commit, the datetime would corrospond to the date associated with that identifier (the date the value was created, not the date the value was read by Porchlight), and the value is an integer value.
Example value source:
def value_source(project_url): """ Acquire a value for the given project_url """ ... return (value_identifier, value_datetime, value)
Value source configuration is described in more detail above.
A value calculator is a Python callable that takes an undeployed value three-tuple, a deployed value three-tuple, and calculates and returns a value difference between them. This value can be thought of as "unshipped value".
Example value calculator:
def value_source(undeployed_value_tuple, deployed_value_tuple): """ Calculate a value from the given undeployed and deployed value tuples. """ ... return value
Value calculator configuration is described in more detail above.
How to test the software
If the software includes automated tests, detail how to run those tests.
Document any known significant shortcomings with the software.
Instruct users how to get help with this software; this might include links to an issue tracker, wiki, mailing list, etc.
If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.
This section should detail why people should get involved and describe key areas you are currently focusing on; e.g., trying to get feedback on features, fixing certain bugs, building important pieces, etc.
General instructions on how to contribute should be stated with a link to CONTRIBUTING.
Open source licensing info
Credits and references
- Projects that inspired you
- Related projects
- Books, papers, talks, or other sources that have meaniginful impact or influence on this project