diff options
| -rw-r--r-- | README.md | 65 |
1 files changed, 45 insertions, 20 deletions
diff --git a/README.md b/README.md index 8b619d0..5e52034 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,57 @@ GAnarchy ======== -<!-- FIXME this README is crap --> -GAnarchy is a Project Page Generator focused on giving forks of a project the same visibility as the original repo. -More importantly, it's a tool to help fight against BDFLs and other forms of centralized project management. +GAnarchy is a decentralized project hub. Additionally, it's an attempt to +decentralize development: What if you could build a community around +fragmentation? GAnarchy proposes a development model that is not centered +around "sending patches". -GAnarchy is a decentralized project hub with the goal of enabling "zero-ownership" projects. +There are not and there never will be Pull Requests, Merge Requests or Email +on GAnarchy. -Basic Usage ------------ +Quick Start Guide +----------------- -First, initialize the database with `ganarchy.py initdb`. The database is stored in the XDG data home, as per XDG spec. +First, initialize the database with `python -m ganarchy initdb`. The database +is stored in the XDG data home, as per the XDG Base Directory specification. -Then create or edit the file `$XDG_CONFIG_HOME/ganarchy/config.toml`. It should contain the following items: +Then create or edit the file `$XDG_CONFIG_HOME/ganarchy/config.toml`. It +can contain the following items, some of which are required: ``` # Example GAnarchy config -# The base_url is the web address of the GAnarchy instance +# The base_url is the web address of the GAnarchy instance. # Restrictions: MUST be present. SHOULD be https. base_url = "https://ganarchy.autistic.space/" -# The title is shown on the homepage. If not present, defaults to "GAnarchy on [base_url's hostname]" +# The title is shown on the homepage. If not present, defaults to +# "GAnarchy on [base_url's hostname]". title = "GAnarchy on autistic.space" -# The projects table is made up of "project commit" hashes (see below for project commit) +# The repo_list_srcs table references external repo lists, which MUST follow +# the same format as this config but only the projects table (see below) is +# used. +[repo_list_srcs] +# Each repo list src is an URL that points to the repo list. +# Restrictions: active MUST be present. MUST be https. +"https://ganarchy.autistic.space/index.toml" = { active=true } +# active=false won't be processed. +"https://ganarchy.github.io/index.toml" = { active=true } + +# The projects table is made up of "project commit" hashes (see below for +# what a project commit is) [projects.385e734a52e13949a7a5c71827f6de920dbfea43] # Each project is made up of repos and branches # HEAD is special and refers to the default branch -# Restrictions: active MUST be present, file URLs are disallowed +# Restrictions: active MUST be present, file URLs are disallowed. "https://cybre.tech/SoniEx2/ganarchy".HEAD = { active=true } -# repos/branches with active=false will not be shown or updated +# repos/branches with active=false will not be shown or updated. "https://cybre.tech/SoniEx2/ganarchy".broken = { active=false } ``` -A project commit is a commit that *must* start with `[Project]` followed by the project name, and may have an optional description. +A project commit is a commit that *must* start with `[Project]` followed by the +project name, and may have an optional description. Example project commit: @@ -45,19 +62,27 @@ A Project Page Generator written in Python, focused on giving forks of a project the same visibility as the original repo. ``` -To generate the output pages: +The following command generates the output pages in the "public" directory: ``` -ganarchy.py cron-target index > index.html -ganarchy.py cron-target config > config.toml # if federation is desired -ganarchy.py cron-target $PROJECT_COMMIT > project/$PROJECT_COMMIT/index.html # for each project +python -m ganarchy run public ``` -It's recommended to use a wrapper script to generate the project pages. `ganarchy.py cron-target project-list` may be of use. +You can change the directory by changing "public" to another name, e.g.: + +``` +python -m ganarchy run output +``` + +generates an "output" directory instead. You can then upload the result +to your service of choice. Advanced Usage -------------- -In addition to the basic configuration above, you can also place your own templates in `$XDG_CONFIG_HOME/ganarchy/templates`. +In addition to the basic configuration above, you can also place your own +templates in `$XDG_CONFIG_HOME/ganarchy/templates`. The current templates are: `index.html`, `index.toml`, `project.html`. + +<!-- TODO further docs on advanced usage? --> |