Eventually, this all goes on-chain, read our đź“ś whitepaper đź“ś, we are on-chain governance maximalists!
This landing repo is intended to be the best starting place to get a coherent view of how information is organised in this GitHub organization.
For software development we try to follow the git-flow branching model with some minor differences:
developmentbranch instead ofdevelop.- feature branches should be created in contributors' own fork of the repo.
- for more collaborative long running feature development, a feature branch may be created by the maintainer on the central repo.
The central repos will have multiple members of the core team with write access, but there will be one designated maintainer or "product owner" and responsible for the final product. The maintainer must approve either directly or by delegation (accepting other members' reviews) PRs to be merged.
The core team, maintainers and outside contributors are encouraged to follow these general guidelines when contributing to the code repositories:
- All contributions should be via pull requests.
- Do not create arbitrary branches or push directly to the central repo
masterordevelopmentbranches. - Do not force push branches.
- Avoid rebasing branches of open PRs to help preserve conversation history.
- Authors must always request a review for their PRs, Exception: It does not alter any logic (e.g. comments, dependencies, docs, file organisation), then it may be merged once CI checks are complete.
- Author should avoid merging their own PR, if it hasn't been reviewed and approved.
- If travis or other CI integrations are configured for the repo, avoid merging PRs that fail checks.
- When the maintainer is opening a PRs they must still request a review from a core team member.
Each repository may have contributing guidelines detailed in their README files. The maintainer must ensure this contribution section is linked to as the base guideline.
Documentation, project management, and other or non-code repositories should try to follow similar PR etiquette if it makes sense but exceptions can be made as changes usually don't require the same level of review.
This is the set of active repos to which this document refers:
| Repo | Description | Maintainer |
|---|---|---|
| apps | The Pioneer application. | @siman |
| substrate-node-joystream | The Joystream substrate node. | @mnaamani |
| storage-node-joystream | The storage node application. | @mnaamani |
| query-node-joystream | Query node for the Joystream Platform. | @paul |
| Repo | Description | Maintainer |
|---|---|---|
| joystream | The Joystream landing repo. | @bedeho |
| joystream-website | The Joystream website. | @bwhm |
| whitepaper | The Joystream whitepaper. | @bedeho |
| communications | The Joystream communications workspace and archive. | @bwhm |
| helpdesk | Information and guides for users and contributors. | @bwhm |
| bounties | Bounties and testnet payout overview. | @blrhc |
| design | Joystream brand guide and assets. | @bwhm |
| manifesto | The Joystream manifesto. | @bedeho |
| joystream-content-system | A repo containing information and resources about the Joystream content system. | @bwhm |
| Repo | Description | Maintainer |
|---|---|---|
| substrate-runtime-joystream | The Joystream substrate runtime. | @mnaamani |
| substrate-content-directory-working-group-module | A working group module for the Joystream content directory. | @bedeho |
| substrate-versioned-store-permissions-module | Permissioned access to the versioned store. | @mnaamani |
| substrate-versioned-store-module | A versioned data store Substrate module. | @siman |
| substrate-recurring-reward-module | Recurring periodic minting of rewards for recipients. | @mnaamani |
| substrate-token-minting-module | Transferrable capacity constrained token minting. | @mnaamani |
| substrate-hiring-module | Hiring for on-chain organisations. | @bedeho |
| substrate-stake-module | Managed staking, unstaking and slashing. | @mnaamani |
| substrate-forum-module | The on-chain Joystream community forum. | @bedeho |
| substrate-module-template | Substrate runtime module template. | @mnaamani |
| Repo | Description | Maintainer |
|---|---|---|
| versioned-store-js | A typescript library for versioned object store. | @siman |
| query-resolver-toolkit | A toolkit for query resolution. | @yourheropaul |
| status-endpoint-joystream | The status endpoint for the Joystream network. | @bwhm |
Until the Joystream mainnet goes live, a sequence of test networks will be rolled out and deployed, and this section covers this activity.
Constantinople
| Network | Started | Ended | Release Plan |
|---|---|---|---|
| Acropolis | 24.06.19 | 13.03.20 | Link |
| Athens | 17.04.19 | 24.06.19 | Link |
| Sparta | 28.02.19 | 29.03.19 | N/A |
| Mesopotamia | 21.12.18 | 28.02.19 | N/A |
The reason this is placed in public view on GitHub is two fold:
-
Open Invitation: Serves as an open invitation for anyone who wants to learn, comment and possibly contribute, to the current or future development of the Joystream project.
-
Best Practices: Establish best practices which can be replicated by the platform, when it is fully live, in how to collaboratively build and manage the platform using open tools. In particular, the current plan is that the platform has a built-in GitHub equivalent, which thus would allow the use of these conventions.
Meeting itineraries are prepared on a case by case basis, depending on the context, and a template for this, as well as an index of archived itineraries, can be found here.
- Description: Everyone states, within 1 minute, what they accomplished the prior day, and what the goals are for the day. After this, people can start separate calls which need not be conducted in plenum.
- When: Every day at 10am (GMT)
- Where: Zoom
- Participant: Core Jsgenesis team must be present, anyone else is welcome (join Telegram for invite).
- Record&Publish: YES, if no participant objects.
- Description: Everyone states individual:
- OKR Tracking: Track your OKRs and OKR assignments
- Health Comments: Any points you wish to discuss related to things like team health, code health, workflow/system health etc.
- Weekly Priorities: Your top 3-5 priorities this week. Not the same as your tasks today.
- Announcements: Anything you think should be brought to everyone's attention.
- When: Every working Tuesday at 10am (GMT)
- Where: Zoom
- Participant: Core Jsgenesis team must be present, anyone else is welcome (join Telegram for invite).
- Record&Publish: YES, if no participant objects.
- Description: Discussion concerning testnet planning and release.
- When: On-demand
- Where: Zoom
- Participant: Core release team must be present, anyone else is welcome (join Telegram for invite).
- Record&Publish: YES, if no participant objects.
Project management is primarily centered around planning and tracking OKRs. OKRs is a planning and project management system, which can be reviewed in further detail here.
A key result can be assigned to a mix of people or other objectives. The assignment set of a key result constitutes the set of relevant actors, directly or indirectly - for OKRs, that are working to satisfy the result. Each assignment is given a weight from 0 to 1, and the total weight across an assignment set is 1. Some key results, in particular for very higher order OKRs, may not have assignments at all times.
The OKRs can be classified into two separate families of types, first:
-
Project OKRs: Project OKRs can run over multiple years and are graded very rarely. They contain the root objectives that require no deeper justification. Every other objective must be justified directly, or indirectly through another key result, by virtue of its relevance to the project OKRs. The current set of such OKRs can be found below.
-
Quarterly OKRs: Every quarter, new OKRs for the given quarter are derived, referred to as quarterly OKRs. Only OKRs which have independent objectives are formally referred to as quarterly OKRs, any derivative OKR is not, even if derived at the start of a quarter. Importantly, they should contain very little detail about releases. The current set of such OKRs can be found below.
-
Release OKRs: Releases are planned one after the other on a rolling basis, and the release OKRs correspond to a single release. Only OKRs which have independent objectives are formally referred to as release OKRs, any derivative OKR is not, even if derived at in the context of a release. The current set of such OKRs can be found below
and then second:
-
Group OKRs: Group OKRs are defined by the set of stakeholders assigned to the key results, and in particular that there is more than one person involved. Typically this could be a set of people working as a team on some topic or problem. In principle, such an OKR can be rationalised by a mix of release and quarterly OKRs, but in practice, it will most often just be one or the other. These OKRs should be flexible in time scope and should be reorganized if circumstances change. The current set of such OKRs can be found below.
-
Personal OKRs: The exact same thing as group OKRs, only applying to a single person only. The current set of such OKRs can be found below.
Note: Any OKR from the first family is
-
never a personal OKR, even if assigned to a single person
-
never a group OKR, even if assigned to a multiple persons
The following figure attempts to summarise how these OKR families and types are related, and their relevant temporal scopes.
All OKRs, except the project OKR, should be derived, in terms of its objective, from one or more key results of already existing higher order OKRs.
In order to keep track of whether a key result and thus the corresponding objective will in the end, be satisfied, forecasts are tracked throughout the lifetime of an OKR. Each OKR has its own periodic tracking of progress, and to compute its forecasted value, do as indicated in the example figure below.
Briefly, do a topological sort of the key result graph, where having an objective in the result assignment set counts towards the indegree. Then just do ascending weighted averaging of scores, where key results are simply averaged into objective scores. Importantly, in order to do this, one has to get personal scores on key results, and there are two modes of doing this:
-
Naive (n): Simply evaluate the key result statement directly based on available data at the time. For example, if the result is
Get $100 in revenue, and one has $20 so far, then the score would be 0.2. This method is often suitable, but no if partial work is unlikely to have had any real world effects while tracking. -
Estimate of Work Done (ewd): Fraction of estimated total hours required that have been completed. This means that, if the estimate of total time required changes, then the score can change, even there is not change in actual hours completed.
The mode used depends on the nature of the key result.
The template used for recording and tracking OKRs has the following form:
- Active from:
<When the OKR is set/live> - KR Measurement Deadline:
<When the final grading is conducted> - Tracked:
<Time interval at which OKR is tracked> - Tracking Manager:
<Name of person responsible for doing tracking, at a given interval, and final grading> - Key Results:
<If all key results have the same assignment set, write here><Statement of Key result><n/ewd>
<Name of assignee>:<assignment weight>- ...
- **Final Score:**
| Date | KR #1 | ... | Total |
|---|---|---|---|
<final date> |
(<... assignment set scores>) Total KR score |
... | Final Objective Score |
- Notes
<Notes on setup/tracking/final score if necessary>- ...
- Tracking:
| Date | KR #1 | ... | Comments |
|---|---|---|---|
<date1> |
(<... assignment set scores>) Total KR score |
... | Tracking comments |
<date2> |
(<... assignment set scores>) Total KR score |
... | Tracking comments |
All releases have the following branding materials, which should be summarised in a markdown Branding Document:
- Name: Our current naming system is important historical ancient cities in the development of new political systems. It's still not clear if we will just stick to ancient cities, or if we will also move forward in time (TBD).
- Naming Rationale: A brief 40-150 word text about the significance of this city in our context.
- Goal: A brief 100-200 word text about the technical and community goals we are trying to achieve.
- Logomark: Illustrated logomark corresponding to name.
All releases should have a corresponding release directory in the /testnets directory of this repo, and it should have the following structure:
release_nameREADME.md: Release document.specification.md: Testnet specification./branding: A directory which includes a branding document and related assets, as described in the branding section.
Each release is directed by a Release Manager (RM) who is responsible for:
- Conduct weekly status meetings (Monday), for each Tracking Issue of the release.
- Based on this information, set a weekly tracking score for each KR to be presented and discussed with the team as part of the Tuesday all-hands.
- Preparing all administrative pull requests for the release on this repo.
- Follow up the Release Milestones
A Tracking Issue is a GitHub issue which evolves, and at any given time holds a list of TODO items, with corresponding completion status and possibly responsibility indicator (i.e. each item has one responsible actor). TODO items are grouped into Tracking Issues based on what most deeply facilitates effective collaboration and progress tracking.
- Every Monday, each Tracking Issue will be discussed in a video meeting between all assigned team members and the Release Manager.
- These meetings should be highly focused and kept at a reasonably high level.
- If a discussion gets to deep, the RM can request that the relevant participants schedule a new meeting to address the issue.
- The Release Manager will then update the Tracking Issue if necessary by changing/adding/removing/reassigning tasks, and checking off concluded tasks.
- A concise summary of the meeting shall be added as a comment.
As part of the Release Plan, a set of Milestones are set, with a "target date". Similar to the concept of Tracking Issues, the "Live Milestones" is a GitHub issue which evolves. Experience has shown, that during a release cycle:
- we may require adjusting the target date(s)
- we may want to add or remove certain Milestones
- we may want to adjust the scope of certain Milestones
In addition to the weekly follow-up meetings addressed above, each release cycle includes the more formal meetings listed below.
Launch MeetingUser Stories MeetingRelease Plan Finalization MeetingRelease Checklist MeetingLessons Learned
The RM is responsible for scheduling, conducting and taking minutes. Go here to read about previously held, and scheduled release meetings.
TODO
WIP: describe how we use GitHub, in particular
- repo creation, naming and formatting policies
- how to use this repo, in particular managing label sets, projects, etc.
- explain gitflow
- collaboration, membership status policies.