✨ What is RTFM? 📚 The Social Coding Guide ✨

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.

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, please follow it in all your interactions with the project.

Knowledge Base

• ZI Wiki
• Zsh Plugin Standard
• Zsh Native Scripting Handbook

Need some help regarding the basics?🤔​

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
• Cloning a Repo
• How to create a Pull Request
• Getting started with Git and GitHub
• Learn GitHub from Scratch

Submitting Contribution​

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

Step 0 : Find an issue​

• 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​

• 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.

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.

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

Step 2 : Branch​

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

# 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​

• 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:

# 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​

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

# 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​

• 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:

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

Step 6 : Pull Request​

• 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. 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)

Recommendations​

• Any files to support the preferred editor should be collaborated and respected across organization repositories e.g: editorconfig.
• Write comments extensively as we use doxygen for shell scripts which parses Zsh and Bash scripts.
• Get familiar with Conventional commits and ZenHub.

Issues and feature requests​

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 to see if it's already being discussed. You can help us by submitting an issue on GitHub. 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 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, 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

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.

  • 🎉 Initial commit
  • 🎨 when improving the format/structure of the code
  • 🐎 when improving performance
  • 📚 when writing docs
  • ✏️ when fixing typos
  • 🐛 when fixing a bug
  • 🔥 when removing code or files
  • 💚 when fixing the CI build
  • ✅ when adding tests
  • 🔒 when dealing with security
  • ➕ when adding new dependencies
  • ⬆️ when upgrading dependencies
  • ⬇️ when downgrading dependencies
  • 👕 when removing linter warnings
  • 🚧 work in progress
  • ✨ when adding feature
  • 💄 when improving UI
  • 💎 new release
  • 🚀 Anything related to Deployments/DevOps

Do not add images, rather 👇​

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

How to do that?​

• You can do that by hosting all your images and screenshots to any images hosting sites such as imgur, imgbb, postimages.
• Then link your uploaded images to README files.

Community membership​

New contributors​

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

Member​

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 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​

• 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.

Membership request