Forking

Return to Projects documentation.

New in version 0.1.8.

In many situations we need to clone one project, make some changes (progress), review them and eventually merge them into upstream. Or we know that our changes won’t be accepted (or shouldn’t be) but we still need to make them for our own reasons. When we talk about software repository we would call that clone a branch. But if we refer to project as a whole, we often call this projects’ copies forks.

django-projector allows user to fork another project not only within it’s own context. It is also possible to fork a project from external location, i.e. from Bitbucket.

Internal fork

This is standard fork functionality which may be found at other forges. Procedure is simple:

1. Jack decides to fork project named joe’s project
2. At the joe’s project main page Jack clicks on Fork button
3. Jack is redirected to his new forked project named as original one

External fork

At his or her dasboard, user can find a Fork project button. This does not refer to internal fork. External forking only allows to fork from external location.

To enable this functionality, it’s necessary to set :setting:`PROJECTOR_FORK_EXTERNAL_ENABLED = True <PROJECTOR_FORK_EXTERNAL_ENABLED>` at settings file. Moreover, :setting:`PROJECTOR_FORK_EXTERNAL_MAP` dict setting should be set properly (see Configuration).

Warning

We DO NOT take any responsibility caused by using external forking. Reason is simple - some users could use this functionality to attack external hosts by sending crafted values to the fork form. Values should be validated by the form first, though.

How to write external fork form

External fork form should subclass projector.forks.base.BaseExternalForkForm and implement fork method:

• fork(): this method should implement action required to create projector.models.Project instance. Note that real fork procedure is fired by project creation handler. We may create a project in whatever way we want here but most basic scenario is to pass author, name and public attributes to the constructor of projector.models.Project class.

  Note

  All exceptions at fork method should be caught and eventually propagated but with type :error:`ProjectorError` (or a subclass of it). It is necessary for projector.forms.ExternalForkWizard to properly notify user if any error has occured during forking process. Those are not validation errors as fork method should be called only after form is cleaned.

Moreover, projector.forks.base.BaseExternalForkForm subclasses need to be initialized with django.http.HttpRequest as first positional argument (this is required for further form’s validation).

Base fork form class comes with one field as_private. After form validation it is possible to check if project should be forked as public or private by calling is_public form’s method. This method would return True or False.

After form is implemented we can hook it at the :setting:`PROJECTOR_FORK_EXTERNAL_MAP`.

We advice to review code of projector.forks.bitbucket module to see full example.