✨ What is RTFM? 📚 The Social Coding Guide ✨
Tags: opensource, productivity, github, codenewbie
Published: 2022-01-27 23:39:16

---
title: ✨ What is RTFM? 📚 The Social Coding Guide ✨
published: true
date: 2022-01-27 00:00:00 UTC
canonical_url: https://z-shell.pages.dev/blog/contributing-guidlines-update
tags: opensource, productivity, github, codenewbie
---

<div align="center">

![image](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7ide1wh8bnzi9j23p1xb.jpg)

</div>

---

## Quick intro

I noticed that quite a popular topic became git, but sadly with so much misleading and incorrect information. I decided to my share one my version for social coding.

The problem is that there is no correct way to contribute, same as there is no best distribution in open-source or best shell environment and much more. But let's concentrate on contributions as the open-source principles are a separate and huge topic.

Long story short in most cases every organization, project, or user has its preferences and specific needs. So everyone else has more or less to adapt every time they join. This is where providers like GitHub became essential to collaborate or projects as https://www.conventionalcommits.org come into existence to unify and eliminate the unnecessary time spent for every project, etc. Most developers even have a meme called: [RTFM](https://en.wikipedia.org/wiki/RTFM).

Recently I read a post: "Commit like a boss", 
which basically gave some basics and then stated that professionals commit messages like - quote: `git commit -m "today I changed some theme colors and added a few of mine because your colors suck I fkin hated them so I got rid of them. Apart from this I also added a Palette section it's was a hell lot of work I better get a raise :P"`. Which is really funny and I would like to see the developer reading this 'daily news' when he has to find the issue and fix it.

Below are my preferences for the organization. Which is always updated with GitHub Docs and other best practices. Hope someone will read it, put the pieces together and will benefit from it. I kept it as minimal as I can and tried to include the specifics that the project requires, so it can be applied across organization repositories once.

---

When contributing, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Please note we have a [code of conduct](https://github.com/z-shell/zi/blob/main/docs/CODE_OF_CONDUCT.md), please follow it in all your interactions with the project.

### Knowledge Base

- [ZI Wiki](https://z-shell.pages.dev)
- [Zsh Plugin Standard](https://z-shell.github.io/docs/zsh/Zsh-Plugin-Standard.html)
- [Zsh Native Scripting Handbook](https://z-shell.github.io/docs/zsh/Zsh-Native-Scripting-Handbook.html)

### Need some help regarding the basics?🤔[​](#need-some-help-regarding-the-basics "Direct link to heading")

You can refer to the following articles on the basics of Git and GitHub and also contact the Project Mentors, in case you are stuck:

- [Forking a Repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
- [Cloning a Repo](https://help.github.com/en/desktop/contributing-to-projects/creating-an-issue-or-pull-request)
- [How to create a Pull Request](https://opensource.com/article/19/7/create-pull-request-github)
- [Getting started with Git and GitHub](https://towardsdatascience.com/getting-started-with-git-and-github-6fcd0f2d4ac6)
- [Learn GitHub from Scratch](https://lab.github.com/githubtraining/introduction-to-github)

### Submitting Contribution[​](#submitting-contribution "Direct link to heading")

Below you will find the process and workflow used to review and merge your changes.

#### Step 0 : Find an issue[​](#step-0--find-an-issue "Direct link to heading")

- Take a look at the Existing Issues or create your **own** Issues!
- Wait for the Issue to be assigned to you after which you can start working on it.

Note: Every change in this project should/must have an associated issue.

#### Step 1 : Fork the Project[​](#step-1--fork-the-project "Direct link to heading")

- Fork the Repository. This will create a Local Copy of the Repository on your GitHub Profile. Keep a reference to the original project in `upstream` remote.

```shell
git clone https://github.com/<your-username>/<repo-name>
cd <repo-name>
git remote add upstream https://github.com/z-shell/<repo-name>
```

- If you have already forked the project, update your copy before working.

```shell
git remote update
git checkout <branch-name>
git rebase upstream/<branch-name>
```

#### Step 2 : Branch[​](#step-2--branch "Direct link to heading")

Create a new branch. Use its name to identify the issue you addressing.

```shell
# It will create a new branch with the name Branch_Name and switch to that branch.
git checkout -b branch_name
```

#### Step 3 : Work on the issue assigned[​](#step-3--work-on-the-issue-assigned "Direct link to heading")

- Work on the issue(s) assigned to you.
- Add all the files/folders needed.
- After you've made changes or made your contribution to the project add changes to the branch you've just created by:

```shell
# To add all new files to branch Branch_Name
git add .
# To add only a few files to Branch_Name
git add <some files>
```

> A very good habit to use `git add -u` and `git add <some file(s)>` as it adds only previously tracked files and skips all others until added by specifying the name of the file(s). This habit protects from accidental exposure of files.


#### Step 4 : Commit[​](#step-4--commit "Direct link to heading")

- To commit give a descriptive message for the convenience of the reviewer by:

```shell
# This message gets associated with all files you have changed:
git commit -m "message"
```

**NOTE**: A PR should have only one commit. Multiple commits should be squashed.

#### Step 5 : Work Remotely[​](#step-5--work-remotely "Direct link to heading")

- Now you are ready for work to the remote repository.
- When your work is ready and complies with the project conventions, upload your changes to your fork:

```shell
# To push your work to your remote repository:
git push -u origin Branch_Name
```

#### Step 6 : Pull Request[​](#step-6--pull-request "Direct link to heading")

- Go to your repository in the browser and click on compare and pull requests. Then add a title and description to your pull request that explains your contribution or use projects template if any.


### Clean Pull Request (summary)

Contributing is also a great way to learn more about social coding on GitHub, new technologies and their ecosystems, and how to make constructive, helpful bug reports, feature requests, and the noblest of all contributions: a good, clean pull request.

- Create a personal fork of the project on GitHub.
- Clone the fork on your local machine. Your remote repository on GitHub is called `origin`.
  - `git clone https://github.com/{YOUR-USERNAME}/zi`
- Add the original repository as a remote called `upstream`.
  - `git remote add upstream https://github.com/z-shell/zi.git`
- If you created your fork a while ago be sure to pull upstream changes into your local repository.
- Create a new branch to work on! A branch from `develop` if it exists, else from `main`.
- Implement/fix your feature, comment on your code.
- Follow the code style of the project, including indentation.
- If there are related tests please run them.
- Write or adapt tests as needed.
- Add or change the documentation as needed.
- Squash your commits into a single commit with git's [interactive rebase](https://docs.github.com/en/get-started/using-git/about-git-rebase). Create a new branch if necessary.
- Push your branch to your fork on GitHub, the remote `origin`.
- From your fork open a pull request in the correct branch. Target the project's `develop` branch if there is one, else go for `main`!
- Once the pull request is approved and merged you can pull the changes from `upstream` to your local repository and delete your extra branch(es).

> Always write your commit messages in the present tense. Your commit message should describe what the commit when applied, does to the code – not what you did to the code. ([examples](https://www.google.com/search?q=english+%22present+tense+example%22)) 


### Recommendations[​](#recommendations "Direct link to heading")

- Any files to support the preferred editor should be collaborated and respected across organization repositories e.g: [editorconfig](https://gist.github.com/ss-o/1e8d9f3a710f78330a09ccc47ef6ddb2).
- Write comments extensively as we use [doxygen for shell scripts](https://github.com/z-shell/zsdoc) which parses Zsh and Bash scripts.
- Get familiar with [Conventional commits](https://www.conventionalcommits.org) and [ZenHub](https://go.zenhub.com).

#### Issues and feature requests[​](#issues-and-feature-requests "Direct link to heading")

You've found a bug in the source code, a mistake in the documentation or maybe you'd like a new feature? Take a look at [GitHub Discussions](https://github.com/z-shell/zi/discussions) to see if it's already being discussed. You can help us by [submitting an issue on GitHub](https://github.com/z-shell/zi/issues). Before you create an issue, make sure to search the issue archive -- your issue may have already been addressed!

Please try to create bug reports that are:

- _Reproducible._ Include steps to reproduce the problem.
- _Specific._ Include as much detail as possible: which version, what environment, etc.
- _Unique._ Do not duplicate existing opened issues.
- _Scoped to a Single Bug._ One bug per report.

**Even better: just submit a pull request with a fix or new feature!**

1. Search our repository for open or closed [Pull Requests](https://github.com/z-shell/zi/pulls) that relate to your submission. You don't want to duplicate effort.
2. Fork the project
3. Create your feature branch (`git checkout -b feat/amazing_feature`)
4. Commit your changes (`git commit -m 'feat: add amazing_feature'`) Z-Shell ZI uses [conventional commits](https://www.conventionalcommits.org), so please follow the specification in your commit messages.
5. Push to the branch (`git push origin feat/amazing_feature`)
6. [Open a Pull Request](https://github.com/z-shell/zi/compare?expand=1)

#### Commit messages

- Use the Present Tense as mentioned above. ("Add feature" not "Added feature").

- Use the Imperative Mood ("Move file to..." not "Moves file to...").

- Limit the subject line to 50 characters

- Wrap the body at 72 characters

- Reference issues and pull requests, where possible.

- Be creative with emojis - it helps to find commits and is easier for the eyes.


    - :tada: Initial commit
    - :art: when improving the format/structure of the code
    - :racehorse: when improving performance
    - :books: when writing docs
    - :pencil2: when fixing typos
    - :bug: when fixing a bug
    - :fire: when removing code or files
    - :green_heart: when fixing the CI build
    - :white_check_mark: when adding tests
    - :lock: when dealing with security
    - :heavy_plus_sign: when adding new dependencies
    - :arrow_up: when upgrading dependencies
    - :arrow_down: when downgrading dependencies
    - :shirt: when removing linter warnings
    - :construction: work in progress
    - :sparkles: when adding feature
    - :lipstick: when improving UI
    - :gem: new release
    - :rocket: Anything related to Deployments/DevOps

#### Do not add images, rather 👇[​](#do-not-add-images-rather- "Direct link to heading")

Instead of adding non-essential images to the repository link them to markdown files.

##### How to do that?[​](#how-to-do-that "Direct link to heading")

- You can do that by hosting all your images and screenshots to any images hosting sites such as [imgur](https://imgur.com/), [imgbb](https://imgbb.com/), [postimages](https://postimages.org/).
- Then link your uploaded images to README files.

### Community membership[​](#community-membership "Direct link to heading")

#### New contributors[​](#new-contributors "Direct link to heading")

New contributors should be welcomed to the community by existing members, helped with PR workflow, and directed to relevant documentation and communication channels.

#### Member[​](#member "Direct link to heading")

Members are continuously active contributors to the community. They can have issues and PRs assigned to them, and pre-submit tests are automatically run for their PRs. Members are expected to remain active contributors to the community.

#### Established community members[​](#established-community-members "Direct link to heading")

Established community members are expected to demonstrate their adherence to the principles in this document. Familiarity with project organization, roles, policies, procedures, conventions, etc., and technical and/or writing ability. Role-specific expectations, responsibilities, and requirements are enumerated below.

#### Requirements[​](#requirements "Direct link to heading")

- Enabled two-factor authentication on their GitHub account.
- Actively contributing to 1 or more repositories alternatively ensure your sponsors are @mentioned on the issue.

This section outlines the various responsibilities of contributor roles in Z-shell. Responsibilities for most roles are scoped to these sub-projects.

| Role | Responsibilities | Requirements | Defined by |
| --- | --- | --- | --- |
| Member | Active contributor in the community | Sponsored by reviewers or multiple contributions to the project | Z-shell GitHub org member |
| Reviewer | Review contributions from other members | History of review and authorship in a sub-project | [CODEOWNERS](https://github.com/z-shell/zi/blob/main/.github/CODEOWNERS) file reviewer entry |
| Approver | Contributions acceptance approval | Highly experienced active reviewer and contributor to a sub-project | [CODEOWNERS](https://github.com/z-shell/zi/blob/main/.github/CODEOWNERS) file approver entry |

[**Membership request**](https://github.com/z-shell/zi/issues/new?assignees=&labels=&template=05_membership.yml&title=team%3A+new+member+request)