Development

All changes to database structure, database documentation, bespoke programs, etc. should under revision control -- committed to the SokweDB master software repository.

Working with the SokweDB Master Software Repository

The SokweDB master software repository may be browsed on the web.

To push or pull from the master repo while on the sokwe server, use the respository's path to identify it. E.g.:

git clone /srv/repos/sokwedb
git pull /srv/repos/sokwedb
git push /srv/repos/sokwedb

Anyone may pull from the master repo over the Internet, with:

git pull https://sokwe.janegoodall.org/repos/sokwedb

The same URL may be used when cloning.

You can perform any operation on the master git repository with ssh and your login. E.g. to push to the master repo over the Internet, use:

git push ssh://YOURLOGIN@sokwe.janegoodall.org/srv/repos/sokwedb

Collaborating on Code; Making Public Repositories

One way to let other people see what you're working on is by creating a publicly available code repository. Public repositories on the SokweDB server act like public repositories on other git hosting services such as GitHub, GitLab, etc., although the web-browser facing interface and associated toolkits differs from service to service. A public repository, no matter the server, is useful when you develop on more than one machine and need to move code between them.

Create a public repository with:

git init --bare /srv/repos/YOURREPONAME

The /srv/repos/ directory holds all the shared repositories. Repositories in this directory are shared on the server, and publicly available to the word for browsing via the SokweDB website.

The advantage of sharing is the ability to view each other's work, work on each other's branches, etc., without having to make changes to the master repository.

Note that the repositories in /srv/repos/ must be bare. This means they contain only revision history and can't be used for development. You will need your own repository(ies), in your home directory or elsewhere, for development purposes.

Permissions on Shared Repositories

All shared repositories, those in /srv/repos, including the SokweDB master software repository, are readable and writable by all developers.

Please take care when making changes to the master software repository.

It is improper etiquette to alter someone else's public repository without their permission.

Tips on Best Practices for Upstream Repositories

Avoid Accidental Pushes to the Master Repository

It is best to have your public repository be the default place to which you push changes. That way you don't accidentally push unproven code to the master repository.

This is most easily accomplished by:

1. Creating your public repository in /srv/repos, as explained above.
2. Cloning that repository to create your working repository, in which development is done.
3. Pulling from the master repository to populate your working repository.

Name the Remote Repositories

Typing a long URL when interacting with the SokweDB repositories can be tedious. Use git remote to assign a short name to, e.g., the master repository:

git remote add blessed ssh://YOURLOGIN@sokwe.janegoodall.org/srv/repos/sokwedb

With this you can git push blessed master, etc., from your local repository to push and pull from blessed when interacting with the SokweDB master repository.

Note that, normally, your remote interactions are only with "bare" repositories, the repositories that are used only for code storage and not for actual development or deployment. Repositories in your home directory, on whatever machine, are normally not bare, and are where development or installation is done.

It is also useful to name the repository in /srv/repos/ on the sokwe server which you use as a personal push/pull endpoint.

Renaming with git remote rename ... is also possible; if you made your repo by cloning the master then you automatically created the name origin to refer to the master repository. Unless you're a senior developer, origin should probably refer to your personal sokwe.janegoodall.org public repository.

The Build System

add text

details on working with the build system can be found here.