Documentation!

README.md

@@ -1,66 +1,15 @@
-# Repositorio de testes 
+# Tainacan
 
-Repositorio pra testar uma estrutura possível para o novo repositorio do WP
+** This is the development repository of a new version of Tainacan. If you are looking for the current stable version, please visit http://github.com/medialab-ufg/tainacan. **
 
-## Descrição do que a gente quer
+Tainacan is a WordPress plugin to build digital repositories. Manage and publish digital collections of any kind.
 
-A gente quer um repositorio onde teremos o codigo fonte do plugin, além de outras ferramentas necessárias para o desenvolvimento, como uma suíte de testes e componentes necessários pra desenvolvimento dos componentes JS
+In this repository, we are building a new version of tainacan. The package will be composed of a WordPress plugin (this repository) and a WordPress Theme. More details of the architecture will be added here soon.
 
-Nesse repositorio, quando tivermos uma versão para publicar, rodaremos um script de build e ele gerará uma outra pasta, com o código do plugin todo pronto, sass e js compilado, etc.
+We plan to mantain this repository well documented to encourage early testers and contributors, so feel free to try it.
 
-## Descrição desse esqueleto
+First, get to know the [key concepts](docs/key-concepts.md) of tainacan and what it does. After that you may want to learn [how to set up your local enviroment](docs/setup-local.md).
 
-Nesse repositorio temos duas pastas:
+We are still in early stages of development, and any help, feedback or contribution is welcome. Please drop us a line opening an issue or via one of our communication channels: 
 
-* src/ - onde fica o código do plugins
-* tests/ - onde ficam as ferramentas de testes
-
-Na pasta `src` temos os arquivos normais de um plugin de WP. Essa será a pasta base do plugin e apenas o que estiver aí dentro é o que vai pra distribuição final do plugin. 
-
-Aí dentro podem haver arquivos sass e js que ainda serão compilados no build.
-
-Na pasta `tests` temos a suíte de testes e as ferramentas para configurá-la. Já tem uns primeiros testes lá de exemplo que testa a classe `Tainacan_Collections`.
-
-Na raíz temos alguns scripts importantes:
-
-* build.sh - é o que faz o build (basicamente compila sass e o q precisar e copia os arquivos pro destino)
-* build-watch.sh - para ficar observando a pasta `src` por mudançar e rodar automaticamente o buid. Útil para quando estivermos desenvolvendo para não precisar rodar o build na mão a cada mudança
-* build-config-sample.cfg - Arquivo exemplo, deve ser duplicado e salvo como `build-config.cfg`
-* compile-sass.sh - compila os arquivos scss do plugin
-* outros arquivos do phpunit que podemos testar pra ver se precisam ficar assim na raíz mesmo.
-
-
-## Montando ambiente e rodando testes
-
-Dá pra perceber que, como esse repositorio tem outras pastas além do plugin, não dá pra gente fazer o clone dela dentro da pasta de plugin do WP e sair usando.
-
-Temos que pensar como fazer isso, talvez um esquema que fique rodando o build e jogando o plugin pra dentro da nossa instalação de testes do WP. É assim que o `build.sh` ta fazendo hoje.
-
-Pra montar o ambiente de testes, foram seguidas essas instruções: https://make.wordpress.org/cli/handbook/plugin-unit-tests/
-
-Basicamente você vai precisar instalar o `phpunit` e aí rodar o comando `tests/bin/install-wp-tests.sh` **passando os parâmetros certos**. Por exemplo:
-
-```
-tests/bin/install-wp-tests.sh wordpress_test root '' localhost latest
-```
-Os parâmetros são:
-
-* nome do DB
-* usuario do MySQL
-* senha do MySQL
-* host do MySQL
-* versão do WP
-
-Esse comando só precisa rodar uma vez. pra instalar o ambiente.
-
-Por padrão, ele instala o wordpress em `/tmp`, mas vc pode alterá-lo para instalar em qq lugar. Caso faça isso, será preciso alterar o bootstrap.php também para apontar para esse novo lugar.
-
-Dessa maneira vc pode ter o seu ambiente de testes instalado em um lugar q não se destrua (como o `/tmp`) e fia ali pra sempre. Vamos melhorar esses scripts de inicialização pra deixar isso mais fácil.
-
-Depois disso, pra rodar os testes, é só rodar o comando `phpunit` a partir da raíz do repositorio.
-
-**Extras**
-
-Vale a pena ver essa série de posts: https://pippinsplugins.com/unit-tests-wordpress-plugins-introduction/
-
-E pra usuários Windows, tem umas instruções lá de como fazer rodar: https://make.wordpress.org/cli/handbook/plugin-unit-tests/#integrating-wp-unit-testing-in-windows
+* twitter: @tainacan_l3p

docs/key-concepts.md

@@ -0,0 +1,59 @@
+# Understanding Tainacan
+
+The typical workflow when you create a Digital Repository with Tainacan is:
+
+* Create a collection
+* Configure which metadata (fields) item in this collections will have
+* Configure the collection
+* Configure which filters will be used when browsing the collection
+* Upload item to the collection or import them from a source
+
+## Collections
+
+A collection is a group of items, that have the same set of metadata. Every item uploaded to your digital repository will be part of a collection. For instance, you could have a "paintings" collections, with metadata such as Title, Author, Country, Tecnique, etc and another collection for "films", with Title, Director, Country and Genre.
+
+For each collection you can set a different set of metadata and they can share common taxonomies, which means you could browse for items in a specific Country, and get both paintings and films in your results.
+
+Collections can also have child collections, which will inherit parent's collection metadata and can add their own set of additional information.
+
+## Items
+
+Items are the actual content of yout repository. The painting, the film, the book and so on. They belong to a collection and have all the metadata configured in the collection.
+
+In WordPress, each item is a post and its post type represents its collection.
+
+## Metadata
+
+Every collection have a set of metadata. They are the description of the items of this collection. 
+
+Each metadata has a set of settings. Is it required? Is it supposed to be unique (an ID number for example)? Does it accept multiple values? What is it Field  Type? (see the complete list of metadata attributes).
+
+(Note: you can import/export presets of metadata)
+
+## Field Types
+
+Field types are the objects that represent the types of metadata that can be used. Examples of Field Types are "Text", "Long text", "Date", "Multiple selection (checkbox)", "Relationship with another item", etc (see full list).
+
+Each field type object have its own settings and web component that will be used to render the interface. 
+
+Field Types can be created via plugins and extend the default set of types shipped with Tainacan.
+
+## Filters
+
+For every collection, you may choose which metadata will be used to filter the results in a faceted search interface. These are the filters.
+
+Filters give the ability to the user to filter items in a collection using a Filter Type.
+
+## Filter Types
+
+Filter types are the different types of interface to filter items in a collections based on one specific Metadata. Examples of Filter Types are "text", "datepicker", "date range picker", "number range slider", etc.
+
+Each Filter Type object have its own settings and web component that will be used to render the interface.
+
+Filter Types can be created via plugins and extend the default set of types shipped with Tainacan. 
+
+## Taxonomies
+
+Taxonomies (or simply categories) that can be created and used to classify items. Typical Taxonomies are Genre, Country, etc.
+
+They are the same WordPress Taxonomies you already know, and they can be shared among many collections.

docs/setup-local.md

@@ -0,0 +1,86 @@
+# Setting up yout local enviroment
+
+This document will run you through setting up your local enviroment and running the tests. If you haven't done it yet, please have a look at [key concepts](key-concepts.md) so you can have a better Understanding of the project.
+
+## Overview
+
+This is the development repository for the Tainacan WordPress plugin.
+
+Overview of folders:
+
+* `docs` - This tecnhinal documentation
+* `tests` - phpunit tests
+* `src` - The actual plugin. Everything outside this folder is not part of the distribution package
+
+This repository includes all the tools needed to develop Tainacan, such as tests and other scripts to compile sass and other things.
+
+## Before you start
+
+Tainacan is a WordPress plugin, so you will need all the basic dependencies you usually have to run a WordPress site, such as PHP and MySQL.
+
+You wil also need:
+
+* `composer` to manage dependencies
+* `sass` to compile sass into css files
+* `phpunit` to run tests
+
+```
+sudo apt-get install phpunit composer ruby
+sudo gem install sass
+```
+
+## Setting up
+
+First of all, clone this repository.
+
+Note that you can NOT clone it directly in the WordPress `plugins` directory. Clone it in a folder of its own and configure your build to point to the your local WordPress `plugins`
+folder.
+
+```
+git clone git@git.github.com:tainacan/tainacan.git
+```
+
+Install dependencies via composer
+
+```
+composer install
+```
+
+And that's pretty much all. Now you will want to set up your tests and your build.
+
+## Build
+
+When we want to build the plugin, we run `build.sh` that basically compiles all the assets (sass), installs any dependence and moves the files to the plugin directory. This compiled version of the plugin will be then added to the official WordPress Plugin repository.
+
+In order to use it, make a copy of `build-config-sample.sh` and name it only `build-config.sh`. Edit it and set the folder in which you want the build to be made.
+
+If you are running a local enviroment, you might want to check `build-watch.sh`. This script will watch your development folder for changes and automatically build the plugin so you dont have to do it manually every time you modify a file.
+
+## Tests
+
+Create a new MySQL database for your tests. This database will be cleaned and restored everytime you run the tests.
+
+Install the WordPress Tests library running the provided script.
+
+```
+tests/bin/install-wp-tests.sh wordpress_test root '' localhost latest
+```
+The parameters are:
+
+* Database name
+* MySQL username
+* MySQL password
+* MySQL host
+* WordPress version
+
+By default, this script installs a copy of WordPress in your /tmp folder. If you want to install it in a different location, edit the file and run it again. (TODO: make a config for that).
+
+Inside `tests` folder, edit the file called `bootstrap-config-sample.php` and inform the folder where you installed your WordPress Test Library. Save the file as `bootstrap-config.php`.
+
+You are done! Now, to run your tests, simply go to the root directory of the repository and type:
+
+```
+phpunit
+```
+
+Also note that the installation script will create a config file in the destination folder with your database credentials. If you have to change it, you will need to edit it there.