Skip to content

Latest commit

 

History

History
309 lines (224 loc) · 14.5 KB

CONTRIBUTING.md

File metadata and controls

309 lines (224 loc) · 14.5 KB
Raw

Welcome to CONTRIBUTING.md

Hey there, fellow Developer !!!... I am happy to see and hyped about making your , probably, first contribution to this open-source repo. I heartily welcome you to your journey in open source contribution. I hope you have fun learning and teaching at the same time. For the Notebook, most of the contribution will be related to content writing like blogs, tips & tricks, tech updates, various documentation, etc.

Setting up Environment

Before you even start working on your content writing, make sure you've got the right environment installed to build the project locally. As this project is based on Jekyll1 framework that is built upon Ruby. We need Ruby, Bundler, and jekyll frameworks to build and test within local systems. The installation process is different from platform to platform, so make sure you follow the instructions properly.

For Ubuntu:

If you're using a Linux distribution - Ubuntu, then follow these steps:

  • Install the Ruby and other prerequisites using the following command:
sudo apt-get install ruby-full build-essential zlib1g-dev -y

Note

Avoid installing RubyGems packages (called gems) as the root user. Instead, set up a gem installation directory for your user account. The following commands will add environment variables to your ~/.bashrc{: .file-path} file to configure the gem installation path:

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
  • Now use the following command, to check whether Ruby has properly installed and its PATH has been set properly.
ruby -v
  • Finally, install Jekyll and Bundler:
gem install jekyll bundler

Important

For Other Linux Distros, check the offical Jekyll webpage. Also make sure, you have installed bundler along with jekyll using the following command:

gem install bundler
  • Use the following command to check whether the bundler and jekyll framework are installed properly or not.
bundle info --path jekyll-theme-chirpy
  • Now, your system is ready to build and use the project locally.

For Windows:

For Windows users, setting up the environment is a bit more involved:

  • Start by downloading and installing the Ruby using RubyInstaller, and choose the latest one with Devkit with default options.

  • At the end of the installation, You'll get CMD asking you to enter options between 1-3. Enter 3 as input, then you can enter 2 if you want to update MYSYS2 but that's totally optional. After all the installation is done, press enter to close the CMD prompt.

prompt-img

  • Open a new command prompt window from the start menu, Use the following command to check whether Ruby has been properly installed and its `PATH`` has been set properly.
ruby -v
  • Now use the following command to install Jekyll and Bundler:
gem install jekyll bundler
  • Use the following command to check whether the bundler and jekyll framework are installed properly or not.
bundle info --path jekyll-theme-chirpy
  • Now, your system is ready to build and use the project locally.

For MacOS:

If you're on MacOS, follow these steps:

[!ALERT] Ensure you have the Homebrew package manager installed. If you're facing any issues while setting up the project in MacOS, check out the Trobleshooting post within the Help Request discussion.

  • Start by installing chruby and ruby-install with Homebrew:
brew install chruby ruby-install xz
  • Install the latest stable version of Ruby (supported by Jekyll[^jekyll-offical-website]):
ruby-install ruby 3.1.3
  • This will take a few minutes, and once it’s done, configure your shell to automatically use chruby:
echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.1.3" >> ~/.zshrc # run 'chruby' to see actual version

Note

If you’re using Bash, replace .zshrc with .bash_profile. If you’re not sure, read this external guide to find out which shell you’re using.

  • Quit and relaunch Terminal, then check that everything is working:
ruby -v
  • After installing Ruby with chruby, install the latest Jekyll & bundler gem:
gem install bundler jekyll
  • Use the following command to check whether the bundler and jekyll framework are installed properly or not.
bundle info --path jekyll-theme-chirpy
  • Now, your system is ready to build and use the project locally.

Build the project Locally

After setting up the environment, you can start contributing to the project:

  • Start by forking the repository.

  • Clone the forked repository to your local machine.

#cloning the repo
git clone https://github.com/<your-github-user-name>/Notebook.git

#entering the project directory
cd Notebook
  • Use the following command to install project dependencies.
bundle
  • Host the static website locally using the following command to preview the current state of the project.
bundle exec jekyll s

Note

Use --incremental argument to update the project live while working on it...

bundler exec jekyll s --incremental
  • If the project build is successful, then you can view the project build that is hosted through your localhost:4000/Notebook. Well done, you have successfully set up the project within your local system.

Getting Started with Contribution

Now that you set up the environment required and started analyzing the project, you have to know a few things about the project structure and its configuration before you start working on your content writing.

Instructions and Guidelines

  • All of the content writing will be done in Markdown (.md) file format. So, Make yourself more comfortable with Markdown syntax through Offical GitHub Documentation.

  • Since this open source is based chripy2 theme jekyll1 project, You're not limited by Markdown only. You can do much more using simple Markdown that provides easy writing while supporting limited HTML elements. Check out the Chirpy-based post creation and text and typography posts to know more.

  • You need to add your details to link the author's details with the posts. You can add your author details to the _data/authors.yml file in the following format:

# Make sure the key_value is unique and not to be a duplicate
unique_key_value:
    name: <author_name>
    twitter: <twitter_id>
    url: <personal (or) contact url>
Looking for an example ? 
shamith_watchdogs:
  name: Shamith Nakka
  twitter: shamith_nakka
  url: https://github.com/iamwatchdogs/

  • It is highly recommended to use the images through CDN links. But if for some reason you are unable to do so, then store them in a new folder that is named after your post and save that folder within assets/img directory as assets/img/<your-project-name>/. Try avoid the process of *storing images within assets/img directory as it reflects the size of the project.

  • Place your content writing files within the _posts directory, following the naming convention YYYY-MM-DD-file-name.md, e.g., 2023-09-27-welcome-to-notebook.md. Use lowercase letters and separate words with a single dash.

  • Each and every content writing file should contain the following meta-data (or) configuration for the project to be successfully built:

---
title: <title>
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [<main_categories>, <sub_categories_1>, ..., <sub_categories_n>]
tags: [<tag_1>, ..., <tag_n>]
author: <respective_author_key_value>
img_path: "/assets/img/<your_img_directory_name>/" <!--(or) respective CDN link -->
image:
  path: <name_of_the_img_for_page_cover>
  alt: <alternative_text>
---

# Your content writing begins here
Looking for an example ? 
---
title: Welcome to the Notebook
date: 2023-09-21 20:34:00 +0530
categories: [Welcome, Guide]
tags: [introduction]
author: shamith_watchdogs
img_path: "/assets/img/welcome-page/"
image:
  path: "welcome-img.jpg"
  alt: "Welcome Page"
---

Important

  • Note that the +/-TTTT in the date section refers the UTC offset. You can find your UTC offset value by searching for your country in the list of UTC. And if you're from India, you can use the above UTC offset from the example.
  • If there is more than one person/author working on a single post, then use authors attribute instead of author. Also, the input for the authors attribute will be a list of unique_key_value representing the authors.
  • It's complete optional to have img_path and image attribute. Use them if and only if, your post requires any images.
  • If your post is using images and you have set the img_path, then you can directly access the images just by using their name.
  • The image attribute will act as the page cover or thumbnail for your post. It's up to you to add a page-cover or not.

These are important instructions and guidelines you need to follow to create a successful post without any issues.

Contributing

Now that you have a basic understanding of the workings of the project, let's talk a bit about the process of contributing...

Step 1: You start you setting up the environment (as discussed above).

Step 2: After setting up the required environment, now build the project locally (as discussed above).

Step 3: Create a new branch to work on your contribution. use the following command:

# create and check out to new branch
git checkout -b <simple-relavent-branch-name>

# check your branch currently in
git branch

Step 4: Now that you got the project up and running within your local machine, start by adding your details as an author to _data/authors.yml file as mention above. Make sure your author key is unique and different from others.

Step 5: Now go ahead and create a new markdown file to work on post to contribute. Make sure you follow the naming convention for the file which is YYYY-MM-DD-your-post-name. And you post name should be all small alphanumeric separated by dashs (-).

Step 6: Make sure you commit every change now, one commit for adding the author name and one for creating a new markdown file. Using the following command:

# Adding or staging the changes
git add .

# commiting the changes
git commit -m "<related-short-message>"

Important

Make sure to commit your each and every change with proper description

  • Step 7: After creating the empty markdown file, add the required metadata (or) configuration as mention above.

  • Step 8: Now, proceed with your content writing using markdown syntax and also using additional features of Chirpy theme2.

  • Step 9: If you have any images, try adding CDN links to the source containing all the images. If not, you can create a new directory using your posts name (separated with dashes -) within the assets/img/ as assets/img/<your-post-name>. And also mention the CDN or directory path in img_path attribute as mention above.

  • Step 10 (optional): After you are done with your post (don't forget to come with each and every change), if you want you can add a page-cover (or) thumbnail to your post. Just mention the image name within the sub-attribute path of the main attribute image.

  • Step 11: After committing all the changes and completion of your work. push your commit to your forked repo, using the following commands:

# check your branch name
git branch

# push your commit to origin repo
git push origin <your-branch-name>

And that is it, you have done it !!!... Now, it's time for the maintainer to review your work and merge your pull request. If there's any issue with your pull request, then the maintainer will contact you and ask for a few changes. And he merges your Pull request, you have successfully made your first open-source contribution that actually helps others.

Everybody can see your work and make use of it. Good job, mate !!...

Rules and Regulations

Here are some ground rules that you need to follow:

  • It's important for you to commit to each and every change. Don't just finish all of your work with a single commit. If you're a newbie, it will only be tolerated 3 times.
  • Sending several pull requests for a single post is not accepted.
  • Your Pull Request will not be merged, if you have modified, changed, or deleted any files or content that doesn't belong to you.
  • Pull Request containing any illegal, NFSW or any other content which doesn't help others in any way possible will be closed immediately.
  • The Pull Request will only be merged if everything seems to be in order. You be notified if you did something wrong, and your pull request will only be merged if the notified changes are made.

Footnotes

  1. GitHub's Jekyll Framework official Page: https://jekyllrb.com ↩ ↩2

  2. Chirpy Jekyll theme's Offical Repo: https://github.com/cotes2020/jekyll-theme-chirpy ↩ ↩2