Using a public repository for community collaboration

Introduction

Using a public repository (everyone can read the code) is a great way to collaborate and share code. The best way to share code is usually through Interfaceware’s online forums, though you might just want to send it to selected people.

Public repositories are free on most Git hosting services, such as Github and Bitbucket. You can allow read and write access for all users, or you can allow read access for all users and restrict write access the designated users. In Github users with write access are called collaborators, and in Bitbucket you simply grant access to users and groups.

To collaborate you just fork/copy a repository (clone command), make (and test) your changes and then upload them back (push command) to the original repository. This is much the same process used for open source software development.

How Iguana uses Git repos [top]

Iguana simply uses Git to store a linear history of code changes. It stores these and a single branch, the default master branch. Iguana does not support multiple branches within a repository. If you need to do parallel development then you should use cloned (forked) repositories as discussed in the next section.

These are the technical details of how Iguana uses a repository:

    • Iguana only uses the default master branch within the Git repository
    • Iguana ignores any other branches within the repository
      Note: Iguana will not be confused by other branches it just ignores them
    • When Iguana imports a channel it loads the latest commit from the master branch
    • When Iguana exports channel it saves it as a commit to the master branch

Tip: It is technically possible to use branching and merging in a repository with Iguana, but we strongly recommend against it.

You would need to create the branches and merges using the Git command line, or a third-party tool. You would also need to copy the code changes manually to the branches. Iguana would happily ignore the branches until they were merged back into the master branch.

If you actually need to do parallel development then we strongly recommend using cloned (forked) repositories as discussed in the next section.

Using a shared repository [top]

First we explain the modern meaning of forking (post DVCS) then give you a bit of history, hopefully this will help you to understand the intention behind the terms forking and branching. Then we explain the process of using a public repository to collaborate. If you don’t enjoy history feel free to jump straight to the process.

The modern meaning of forking

Forking and copying (or cloning) a repository have become pretty much synonymous (though historically this was not the case). These days a fork is usually used to make suggestions for modifying a project, the cloned repository becomes a sandbox where you can try out ideas safely and then offer them back to the original project (this is similar to how a branch is used internally within a repository). This modern method of using a clone repository as a sandbox is exactly how we suggest you collaborate.

A little bit of history

The original meaning of forking a project was to make an independent copy of the source code, and to continue development independently with a different team. The intention of forking a project is that you end up with two separate (incompatible) projects: The original and the forked project. The mechanism used to do this is to make a complete copy of the repository, and different teams work independently on the two separate repositories. With legacy version control systems (i.e., VCS before DVCS), it was nontrivial (probably a manual process) to merge changes from a copy of a repository back into the original. Hence copying (or cloning) a repository became pretty much synonymous with forking a repository (as you would usually only copy/clone when you wanted to fork).

Note: The poster boy for a successful fork is the Apache Web server, which now exists as Apache 1 and Apache 2. The Apache 2 fork is widely regarded as superior to Apache 1, however Apache 1 still has a large user base and development has continued. Perhaps in the future Apache 1 will fade away, who knows, but for now both forks continue to be actively developed.

The original (and still current) meaning of branching a project is similar, you work on a copy of the source code, but changes are merged back into the original project. The intention of branching is to allow team members to work independently on feature additions and bug fixes, and merge them back into the original code at a later date (you can also choose to reject/discard changes and not merge them back). The mechanism used to do this is to make multiple copies of the code internally within one repository. Legacy VCS did not implement branching and merging well, merging was unreliable, and older systems forced you to “check out” code so only one person could modify it at a time.
Note: It is not very efficient make lots of copies, so repositories usually just track the changes from the time you branched (and construct the changed code on demand).

You may have heard the term shallow fork, this is simply forking (copying) a repository with the intention of merging changes back into the original repository. In this scenario you would need to keep your forked repository in sync with the original, therefore you would regularly merge changes from the original repository into your copy. Why would you do this? Legacy version control systems were centralized, so if you were working remotely or were not part of the development team, it is very likely that you could not access the repository directly. Therefore the only option available was to work on a copy. Obviously this was not a great solution, and in fact it is this and other problems is that caused modern DVCS (distributed version control systems) like Git and Mercurial to evolve.

These definitions were all very fine until DVCS (distributed version control systems) came along and muddied the water. In particular DVCS has changed the meaning of forking by making it trivial to clone/copy (fork) a repository and then merge the changes back into the original repository. In fact with DVCS it is standard practice to copy (fork) a repository to your local machine, and later upload (push) the changes back to the original repository. This practice is what used to be called shallow forking, and DVCS just refers to it as forking (easier to say than shallow forking).

This change in the meaning of forking is reflected in this quote from the Github documentation:

A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. Most commonly, forks are used to either propose changes to someone else’s project or to use someone else’s project as a starting point for your own idea.

Notice how “propose changes to someone else’s project” (my highlight) has become the primary purpose of forking. This does not invalidate the original meaning, but fork has become a broader term (including the so-called “shallow fork”) so you now have to pay more attention the context.

How to use a public repository for collaboration

Basically all we want to do is to copy some code, modify it, share it, and get feedback. The best way to share code is usually through Interfaceware’s online forums, though you might just want to send it to selected people. The forums are all about feedback, and questions and replies often include code snippets already. This is fine for simple pieces of code but does not work as well for modules or channels. Exporting your code into a public repository and then sharing a link to the repository makes it much easier to collaborate on complex code like modules and channels.

There are two main reasons for collaboration: You need help to solve a problem, or you solved a problem and want to share the solution. If you are simply sharing a solution it makes sense to use a read-only repository (that other users cannot modify). If you need help to solve the problem then you should use a read/write repository (that other users can modify). When you are using a read/write repository the benefits of source control really kick in, because you can use the commit history to see exactly what changes have been made, and the commit notes (if they are explanatory) to understand why.

These are the steps for collaboration:

  1. Create a public repository.
    • If you are sharing a solution use a read-only repository.
    • If you need help to solve a problem use a read/write repository.
  2. Export the code you want to share to the repository you just created.
    • Alternatively you could copy (clone) the source repository (using the Git command line or third-party tool).
      Note: This may be easier than exporting multiple channels for a complex implementation.
  3. Share the repository through through Interfaceware’s online forums, or send it to selected people.
    • If the base code you are sharing is under development you should copy (pull) changes into the shared repository on a regular basis (so it does not get out of date).
  4. Wait for feedback.
    • The simplest way to do this is to watch the Github or Bitbucket  repositories you are interested in (see the sections below), so you are notified of changes by email.Incorporate changes into your code if desired.

Setup a Github repository [top]

  1. Setup a Github repository
  2. Update the repository permissions to match your requirements:
    • To allow read and write access for all users, go to the settings tab and make sure you uncheck Restrict editing to users in teams with push access only:
    • To allow read for all users and write access for designated users only, go to the settings tab and make sure you check Restrict editing to users in teams with push access only.
    • You can manage collaborators and teams from the options menu (see the Github permissions page for more information):
      Note: The repository owner is automatically added as a collaborator.

Setup a Bitbucket repository [top]

  1. Setup a Bitbucket repository
  2. Update the repository permissions to match your requirements
    • To allow read and write access for all users, go to the Settings>Repository Details and make sure you uncheck Access level – This is a private repository:
    • To allow read for all users and write access for designated users only, go to the settings tab and make sure you check Access level – This is a private repository.
    • You can manage collaborators and teams Settings>Access management (see the Bitbucket repository permissions page for more information):
      Note: The repository owner always has full access.

Connect to a Github repository [top]

  1. For read access follow the procedure Connect to a Github repository with a user and password.
    Note: You will not be prompted for a user and password when connecting to the repo.
  2. For read and write access to an unprotected repository follow the procedure Connect to a Github repository with a user and password.
    Note: You will not be prompted for a user and password.
  3. For read and write access to a protected repository follow the procedure Connect to a Github repository with a user and password.
    Note: You will be prompted for a user password.
  4. For read and write access to a protected repository using SSH follow the procedure Connect to a Github repository using SSH.
    Note: You will not be prompted for a user and password.

Connect to a Bitbucket repository [top]

  1. For read access follow the procedure Connect to a Github repository with a user and password.
    Note: You will not be prompted for a user and password when connecting to the repo.
  2. For read and write access to an unprotected repository follow the procedure Connect to a Bitbucket repository with a user and password.
    Note: You will not be prompted for a user and password.
  3. For read and write access to a protected repository follow the procedure Connect to a Bitbucket repository with a user and password.
    Note: You will be prompted for a user password.
  4. For read and write access to a protected repository using SSH follow the procedure Connect to a Bitbucket repository using SSH.
    Note: You will not be prompted for a user and password.

Watch a Github repository [top]

  1. Log into your Github account.
    Note: If you don’t have a Github account you will need to create one.
  2. Select the repository you want to watch:
    • Enter all or part of the repository name in the search box:
    • Select the repository you want to watch by clicking on its name:
  3. Select Watching from the Watch dropdown menu:
  4. Click on the notifications (bell) symbol at the top right to view your notifications:

    Note: You can also receive notifications by email, if you enable the email option.
  5.  Click on the watching tab to list your watched repositories:
  6. Enable email notifications:
    • Click on change notification settings.
    • Alternatively select Settings>Notifications from the Profile menu at the top right (this menu is available on all screens):
    • Make sure that the Email option is checked for Watching:
      Note: You can also change the email address that notifications and sent to.
  7. You can also follow a Github User.
    Note: You cannot follow a Github Organization.

    • Go to a page belonging to the User you want to follow.
    • One way to do this is to click the User Name link in a repository screen:
    • If the repository is owned by an Organization, you will need to choose the username from the organization members.
      Click on the organization name:

      Click on the name to choose the User:
      And finally click on the user again for one last time:
    • Once you are on a page belonging to the user you can click the green follow button:

Watch a Bitbucket repository [top]

  1. Log into your Bitbucket account.
    Note: If you don’t have a Bitbucket account you will need to create one.
  2. Select the repository you want to watch:
    • Enter all or part of the repository name in the search box at the top right:
    • Select the repository you want to watch by clicking on its name in the list.
  3. Select Watch this repository from the Watch dropdown menu at the top right:

    Note
    : The eye is dark when you are watching a repo and light when you are not.
  4. Choose Inbox from the Avatar menu at the top right to go to your Bitbucket Inbox to view your notifications:

    Note: You can also receive notifications by email, if you enable the email option.
  5.  Click Bitbucket at the top left to go to the Bitbucket home screen (Dashboard) and click on the Watching filter to list your watched repositories:
  6. Enable email notifications:
    • Click on Avatar>Bitbucket settings:
    • Choose Notifications from the left hand menu and make sure that the button under Notifications says Disable Email (which means email is enabled):
    • Choose Email addresses from the left hand menu and change the primary email, to set the email address that notifications and sent to.
  7. You can also follow a Bitbucket User.
    Note: You cannot follow a Bitbucket Organization.

    • Select the teams menu and select the first option, which is the account owner.
    • This will bring it to the Overview tab where you can click the follow button at the top right to follow the owner of the repository (in this case Interfaceware):
    • You can also go to the members tab and choose any User you want to follow:

      Note: When you follow a user their activities will appear on your Dashboard, but you will not receive any notifications.

More Information [top]

 

Leave A Comment?