Skip to content

Using Github

Jump to bottom
Gandalf86 edited this page Jun 3, 2018 · 44 revisions

We are currently trying to use Github for project organization. This is a short overview over the different features offered here. For a more rigorous introduction to general Github usage, please go to https://guides.github.com/

Features

  1. Organization: The current organization name is "wispproject". An organization is a container for repositories.
  2. Repository: A repository can be seen as a sub-project inside the organization. Each repository has its own code tree, wiki and issue tracker. Repositories for Wisp are the wallet, the website, graphics and the 'doc' repository which hosts documentation via the Wiki.
  3. Teams: Access to different repositories is managed via teams. The currently available teams are core developers, web developers, writers and artists. The writers group is meant for long-time community members who can speak/write in the name of the project.
  4. Wiki: You are currently looking at it! There is a list of pages in this wiki on the right side.
  5. Issues: Issues are like tickets that indicate that something specific should be done. For example you can use it to make specific suggestions or report errors. There are separate issue trackers for the documentation, website and the wallet. Tickets can be taken care of by members that have access to the respective repository.
  6. Pull requests: Every Github user can propose a change by forking the repository, changing something on his copy of it, and request a merge (a pull request) to the original source. Pull requests can be accepted by all members that have write access to the respective repository.
  7. Branches are mainly used for code development, to keep track of different versions of the same document. For file management (graphics, documentation) please use the 'Master' branch.

Membership levels

There are 4 kinds of membership levels:

  1. Owner: Owners have write access to everything. They can delete the entire organization, administrate teams, delete stuff, and have write access to all repositories. They are also the only people who can invite new members into the organization. Since this is a security-critical role, only a few trusted members with high security standards should have this role. The current members with "owner" permission are JBG (aka wisp3r) and Gandalf86 (aka bitcoinx2).
  2. Member: Organization members are grouped into teams with different permissions. If you have write permissions to a repository, you can make changes directly, without having to make a pull request. You can also review/accept pull requests of non-members.
  3. Collaborator: Collaborators can be given access to specific repositories without requiring them to be in a team. Members of teams that have the "Admin" permission for a repository can invite external collaborators.
  4. Every Github user can create new "issues" to contribute to the project by reporting errors and pointing out things that should be done. For simple suggestions or general discussion, please use the Discord.

File formats

Github works best if you use clear-text file formats, like TXT files, Markdown (used in the Wiki), LaTeX etc.. Please avoid uploading Word documents, but try to copy the text and make a Markdown file from it.

The Markdown syntax is really simple, here is a short introduction that explains everything you need: https://guides.github.com/features/mastering-markdown/

The only binary file formats uploaded to the repository should be pictures (jpg, png, ...).

Wiki vs. Repository

There are two places you can put text here, one is the Wiki (this one), and the other place is the repository (called "Code" in Github lingo). The Wiki can only contain articles written in Markdown, whereas the repository can contain arbitrary files. However, when you put a Markdown file into the repository, it will be displayed by Github automatically! That means that the repository can be used if you want to organize the text files into subfolders, or mix them with other files.

Whether you put your text into the Wiki or into the repository is up to you. The Wiki is like a central source of information, the repository is more like a store of large amounts of data. If you want your text to be seen by everyone, put it into the Wiki - if not, rather store it in the repository instead.

Proposals

If you want to make a non-technical proposal regarding the project organization or to report an error in the documentation, please use the 'doc' issue tracker: https://github.com/wispproject/doc/issues

Desktop clients

If you find the website interface of Github clumsy too use (especially for moving/renaming binary files like images), you can check out one of these desktop clients that should make the job easier for you:

To use these desktop clients, you will need to set up a "personal access token": https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ For the scope, select only "public_repo". You can then use this token as the password for your Git client.

Security

Setting up two-factor authentication (2FA) is required in order to become a member of the Wispproject organization. For more information, see https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/

Clone this wiki locally