Contributing
Thank you for your interest in participating! This document caters to developers or programmers that wish to write code and directly contribute to the source code of Shabad OS. See Feedback for non-developer contributors.
Most of the contributing model for Shabad OS is shared. A few repo-specific topics of note include: Getting Started / Prerequisites and Scope definitions. These repo-specific topics should be referenced on a repo level, and not on the org level.
#
FeedbackThere are many ways for people to contribute, beyond writing code or programming:
- Ask a question via Slack
- Request a new feature or report unexpected bugs by filing an issue
- Upvote popular feature requests using the thumbs-up/+1 reaction on the first post of an issue
- Follow @shabad_os on Instagram and @shabad_os on Twitter and let us know what you think!
#
PrerequisitesIf you wish to better understand how Shabad OS works or want to debug an issue: get the source, build it, and run it locally. See the contributing doc of the repo for instructions.
#
WorkflowThe general workflow of development (or Git Flow) is to Issues,choose an issue to work on, Branches,create a feature branch, and Pull Requests,submit a pull request.
#
IssuesAfter getting started with the repo, check out the issues list:
- Issues labeled with
Impact: Crit
orStatus: 3hard5me
are good issues to submit a PR for. - Issues labeled
Effort: 0
orEffort: 1
are great if you are in the code for the first time. - If you are contributing significant changes, please discuss with the assignee of the issue before beginning your work.
There should be a pinned issue tracker in each repo with helpful queries. These queries provide lists of potential areas for contributions. Note that, just because an issue exists, does not mean we will accept a contribution for it.
There are a few labels worth noting:
- Effort: 0-109 - The perceived/estimated "points" of effort to resolve the issue
- Impact: {Low, Avg, High, Crit} - The perceived percentage of users the issue affects
- Status: 3hard5me - Issues the assignee needs help to resolve
If an issue is easy to resolve and impacts a majority of users, then its resolution should be prioritized higher.
IMPORTANT
Be sure to discuss with the assignee of the issue, before tackling issues. If there are no assignees, ask to be assigned in a comment.
IMPORTANT
To avoid multiple pull requests resolving the same issue, let others know you are working on it by saying so in a comment.
#
BranchesThe main
branch is used for stable releases. The dev
branch is used for next releases / prereleases and serves as the primary branch of development. Shabad OS follows a fork and pull model. Developers should fork the dev
branch to their personal account. Contributors can create branches off this personal dev
branch and work on them as origin
. Branches should be short-lived and should relate to a single issue from the repo. Avoid updating branches with other branches. Sync your personal branch with upstream
dev with a merge before submitting a PR.
Keep your personal branches separate from each other. Sync your personal branch with upstream
dev
using merge.
PROTIP
If using the gh
cli tool from GitHub to clone your forked repo, you will automatically have origin
and upstream
defined correctly.
Even if you have push rights on the upstream repository, you should create a personal fork. This keeps the Shabad OS repository clean and your personal workflow out of sight.
Branches should be named after the issue they are resolving in the format of username/issue<issue_number>
(e.g. issue 128 for user bhajneet would be bhajneet/issue128
). This is how branches will be named if using the recommended VS Code extension: link:https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github[GitHub Pull Requests and Issues].
PROTIP
If there is no issue related to the work being done, then create an issue for tracking purposes.
See the following GitHub docs for additional guidance:
- Overview of collaborative development models
- Configuring a remote for a fork
- Sync a fork of a repository to keep it up-to-date with the upstream repository
#
Pull RequestsTo enable quick code reviews, create one pull request per issue. Avoid resolving multiple issues in one PR unless they share a root cause. Be sure to follow the Coding Guidelines and keep code changes as small as possible. Avoid pure formatting changes to code that has not been modified otherwise. Pull requests should contain tests whenever possible. The pull requests summary should include changes, tests done, visual before and after, time taken to resolve, and linked issues whenever possible.
PROTIP
Pull Requests are squashed on merge, so title the PR as if it were a single commit according to the first line of Commit Messages.