DEV Community: Gulnur Baimukhambetova

2022 wrapped: open-source

Gulnur Baimukhambetova — Sat, 10 Dec 2022 07:38:33 +0000

Hello everyone! 🙋🏻‍♀️

Today, I wanted to quickly wrap-up my contributions for this year! I do not have Spotify, so this will be my version of "2022 wrapped". 😂

The beginning 🎬

My open-source journey begun only this September, and honestly, I did not expect that I would get so excited about contributions by the end of this year and actually enjoy blogging every time (I am not a writer and never been anywhere close). So, it's pretty shocking to me, but if I knew that open-source is so interesting and welcoming, I'd have started much earlier.

My 2022 🎞

Here are my quick statistics up to this day:

Also, going through this Spotify guide on their personalities approach, and comparing music to projects, I have figured that I am ✨the Nomad✨.

This December ❄️

I am very happy, as I did not only achieve what I was planning earlier in my first post this month, but also made one more contribution.

So, this month, I created new pet animations for VS Code Pets extension, which helped one person to see his favourite animal, chicken, as part of the tool. It was very interesting issue, as we collaborated with Lucas and although I have never met him, the process was very smooth and productive. Now, you can play with chicken while coding in VSCode.

Comment for #339

tonybaloney commented on Dec 09, 2022

Love it!! 👍🏻

View on GitHub

We also decided to keep working together to create more chicken types. So, stay tuned for new black and brown red chickens.

Apart from that, I worked on the this UI issue as part of the Cuttle project, the pvp card game. I was not familiar with the project but managed to figure it out.

Conclusion 😮‍💨

I am very proud of myself, as this year, I have contributed to big companies' projects such as Intel and Pandas, had a variety of contributions ranging from code solutions to translations and even animations, connected with dozens of people all around the world and all due to open-source. 🎉

How to create pixel gif animations 🐔

Gulnur Baimukhambetova — Thu, 08 Dec 2022 08:27:10 +0000

Hello everyone!

Today, I wanted to share what I have learned working on the issue of creating a new pet animations for the VSCode extension VS Code Pets.

Little backstory 🗃

VS Code Pets is one of my favourite extensions which creates a little window next to the code editor where you can play with different pets while working on your projects. I browsed through the open issues inside the repo as I wanted to contribute to the tool and found one which touched me. One guy used the extension a lot but missed his favourite pet - chicken (he even had chicken toy on his GitHub profile photo and chicken emoji in the status message). So, I could not resist but help to add chicken as a new pet.

Adding a chicken as a new pet🐔 #242

MhouneyLH posted on Oct 11, 2022

I am missing my favourite pet - the chicken, so I would like to add it.

I think of like a grain-picking animation, after the chicken was spawned. In additition it should jump and then slowly flies down to the bottom again. One problem I will have is to design the chicken in a pixel-art way. Is there anyone who could deal with this or should I just use the art of other people?

View on GitHub

Task 🎯

He did not know how to create required animations and looked for help. He tried copying one from the internet but you cannot do that due to copyright. You either have to create gifs yourself or look for art with applicable permissions.

Skills 🪄

To be honest, I had absolutely no experience when I decided to work on that issue, so if I could do it, then you definitely can too! All of the software is free and accessible through basic internet browser, so all you need is your enthusiasm.

Process 🛠

As I had no knowledge, my first obvious step was to go the modern library which is YouTube. I found this guy, @Saultoons, who had the series of videos dedicated to basics of pixel animation art. I watched a few videos and got a general idea of where to start, how the frames work and what techniques can be used for different motions.

Then I had to find a tool, where I am going to draw the animations. Aseprite which was featured in the video costed around $20, so I looked for free alternatives and found Pixilart.

Pixilart had very intuitive interface and I could start drawing right away. I googled some pixel chicken pictures to use as a reference and started outlining my base frame. Once I got the basic design which I liked, I added colour and shades to the picture.

This is what I got:

Later, I had to figure out what motions I need to produce. As I was drawing a chicken, I came up with 5 states:

idle / standing
grain picking
walking
fast walking / flying
with a ball (required by the project)

For all of them, I researched and observed the real chicken natural behaviour performing that motion to replicate it in the animation (which meant that I have watched dozens of chicken farm videos on YouTube lol).

Fun fact: chickens move their necks back and forth while walking.

I would break down the motion into multiple frames and try to measure what would be the best time for each of them. Sometimes, you need one part to be quicker than another or on the other hand, some motions are pretty constant.

Tips ✨

Some of the things I learned the hard way, so I guess I will share them, so you do not have to repeat my mistakes:

Always download your work not only as gif but also as pixil. Gif only holds the result and does not perfectly transform back into pixels. So, it will be hard to make changes. However, pixil holds all your project info and will import back perfectly.
If you want to have a transparent background, you will need to color it in some unique to your drawing color that you did not use and go to another tool to make it transparent. You have to use this workaround as Pixilart will not export your gif properly even if it has a transparent background, somehow it will always be white. Onlinegiftools worked well for me.

Some additional work 🧹

Because I was working for the existing project, they had their own requirements regarding the size. So, I had to change that as well. For resizing and cropping, I used ezgif.com.

Final result 🌟

So, at the end, I got my pull request merged and now, chicken can stand, pick grain from the ground, walk, run and hold the ball. 🎉

December is finals first, Christmas later

Gulnur Baimukhambetova — Wed, 07 Dec 2022 09:06:59 +0000

Hello everyone!

This post will be my personal goal setter for the upcoming weeks of my open-source contributions.

December ❄️

This month will be my fourth month in the world of open-source... It might sound like not much, but when you break it down to all the constant work that I have been doing every week, I can totally say that I am proud. When I started in September, I could not imagine that I will love it the way I do now.

2023... not yet 😁

Before the year ends, my plan is to complete a few more pull requests and if possible, challenge myself on new levels.

Idea 💡

During hacktoberfest month, I contributed to the vscode-pets which was a VSCode extension with cute pets to play with while coding. I really liked the general idea, plus, the founder and maintainer of the project was always helpful and quick to respond. It was such a nice contributing experience that I continued making contributions even after the fest was done.

While working on some of the changes, I realized that I have never worked on the VSCode extension before although I am a fan who uses them regularly. So, I decided that it would be quite interesting to dig deeper into it and that in my next contributions I should definitely check out open-source extension repos.

Plan 📜

So, I started looking for the projects and remembered that we have one internal repo in my college that focuses on creating a VSCode extension for all programming students. We brainstormed once of what it should do and came up with some interesting ideas such as cheer-up messages, college-wide or course-wide formatters, connection to internal SSO, etc.

I checked out the issues inside the repo and found one I might work on, but was not sure if it would be a good fit for this contribution as it might take me more than a few weeks.

Therefore, I started to look for an alternative and my first instinct was to go back to the good-old vscode-pets. I saw some issues connected to the creation of new pets and it looked very fun to do. I use this extension now, so having a pet that I know I've helped creating would be amazing. I checked out the top issues connected to this topic and found this. the guy said that he missed his favourite animal - chicken, and that he would really want to see it in the extension... My heart melted and I was hooked right away. 🥺 I have no previous knowledge in animations, so it will be personally very challenging, but I really want to help, so at least I've got the spirit.

Thus, the plan is to complete one of these features by the end of the coming weeks and enjoy the process.

P.s: wish me luck, as I have big final projects for each of my classes due this week as well. 🥲

How to publish your project to npm?

Gulnur Baimukhambetova — Sun, 27 Nov 2022 22:58:41 +0000

Hello everyone!

Today, I created the first release for my SSGulnur tool.

Releases 🚀

As you are building your tool, it is alright to store it on the GitHub and apply it by cloning the repo, building and running it locally following the pre-requisites and instructions outlined in the README file.

However, when it comes to the actual users, not everyone knows how to do it, so it is better to provide releases which are easy to understand, download and use.

For that, I am going to publish my project to the registry so that it can be installed by name.

npm 🗃

As my project is using node.js, my obvious choice of release and package manager was npm.

Approach 👩🏻‍🏫

It does not require much to just publish a package. You can do it by only running the npm publish command, however it will be missing some of the industry standard procedures.

For example, it will not ensure that you are using Semantic versioning (Semver for short) or associate a git tag for each update.

If you do not know what Semver is, I have a brief explanation at the end of the post.

Therefore, we will be using a tool called np, which will

run the tests (if there are any)
update version in package.json according to Semver
create a git tag according to Semver
push the package to Github
push the package to npm
create release notes for every update

all in one command.

Steps 📜

In order to use np there are a few requirements (which you most probably have already met):

Project needs to be a Git repository:
- It needs to have a remote.
- You must have pushed to the remote at least once.
- You also need to make sure your working directory is clean.
- You set up ssh authentication keys
You need to have an npm account

All you have to do is:

Navigate to your projects folder and open a terminal.
Login to your npm account using npm login
Install np globally npm install --global np
Run np and follow the prompt

Optional: add script in package.json for releases using np.

"scripts": {
    ...
    "release": "np"
  },

Tadaaa 🎉

Now, you should have an npm package as well as associated tags and releases on GitHub.

So, my tool can be installed by only using npm i ssgulnur.

My resulting npm package:
https://www.npmjs.com/package/ssgulnur

GitHub releases:
https://github.com/gulyapulya/SSGulnur/releases

Semver 💡

Now, lets talk a little bit about the versioning. Semver is a simple set of rules and requirements that dictate how version numbers are assigned and incremented.

The ideas is that three numbers are used to explain the version and one of them gets incremented depending on how big the change has been.

So the version is structured as MAJOR.MINOR.PATCH and you increase:

MAJOR version when you make incompatible changes (some previous logic cannot be used anymore)
MINOR version when you add functionality in a backwards compatible manner (new features that do not break the previous logic)
PATCH version when you make backwards compatible bug fixes

Contributions can lead to unexpected solutions

Gulnur Baimukhambetova — Sat, 19 Nov 2022 09:56:56 +0000

Hello everyone! 🙋🏻‍♀️

Today, my contribution to one of the external projects was successfully merged after a few days of review. 🎉

Project 👩🏻‍🏫

I really loved working on different open source repositories during the month of Hacktoberfest and I decided to continue making contributions.

One my Hacktoberfest contributions was made to the cool VSCode extension project called VS Code Pets. It allows you to add and play with different cute pets in your VS Code window to boost productivity and help you stay focused.

I personally started using it after I made my first contribution to it and it always brings me joy to see these little pets whenever I start coding.

Additionally, they made a new release where they included all changes including my first contribution and it was so nice to see my name documented as part of it. They keep track of releases in CHANGELOG.md.

Issue 👀

As for the internal project, I worked on the no-code translation issue, here, I wanted to try something more related to my field.

I picked an issue which had very little description, but I have figured it out. It mentioned that whenever a cat receives a ball, its image gets significantly larger, which is not a supposed behaviour.

Solution ✨

First of all, in order to better understand an issue, I has to try to recreate the situation myself. I opened up the VSCode Pets extension and tried throwing a ball at different cats. There are three options: brown, white and black. All of them got larger indeed when a ball was caught. I checked other pets as well to make sure it is solely related to the cats.

Once I confirmed the cases, I started going through the code to understand how it is structured. I was thinking that the issue might be related to how the images get transformed from the running state to the ball caught. However, after spending some time, I figured out that mostly the way the states are managed is applied generally and not only to the cats. So, something else should cause it.

I went back to the issue and saw someone else comment a table of different gif dimensions and ratios. The gifs displayed cat movements in different states. After comparing the gif images, I realized that only the ones with the ball had much smaller dimensions. So, this might have been causing the issue.

However, I never worked with gifs before, so I was not sure how to proceed. I researched myself and found some tools for resizing gif images, but still did not know if it was the right way. So, I decided that it was better to ask the creator of the issue and the maintainer for some recommendations. Later, I was glad I did it as @tonybaloney (Github username) gave me great instructions on what to do. I was initially right and used the tool I found to resize the gifs.

After I was satisfied with the images, I had to test my work to make sure that now the sizes get displayed correctly. I was told to run the extension in development mode, but as I have never developed a VSCode extension before, I did not know how to do it. I found the official documentation with instructions, but the F5 option did not work for me. Luckily, I found another article which mentioned that I can use "Run & Debug" tab and that was how I did it.

Pull request 🔎

Overall, I only had to wait for the reviewer to confirm my changes and approve the pull request. There were no major complications, as I have tested my work.

Conclusion 💡

Previously, I have never worked with the development of VSCode extensions or with gif images, so this was a very valuable experience for me. I expected the solution to be code related, however, the issue has its own idea on how it should be fixed, which was interesting to figure out.

Also, the project did not have a CONTRIBUTING.md file which usually contains all instructions to get started with contributions. So, I had to explore most of the things myself. Therefore, I made another suggestion to the owner.

Comment for #304

gulyapulya commented on Nov 18, 2022

@tonybaloney Also, as a suggestion, it might be great to create a CONTRIBUTING.md file with instructions for contributors who have little knowledge of VScode extension development and other areas to speed up their introduction to the project. :)

View on GitHub

Overall, very happy with what I have achieved. ☺️

New translation experience

Gulnur Baimukhambetova — Sat, 19 Nov 2022 08:58:15 +0000

Hello everyone! 🙋🏻‍♀️

Today, my contribution to one of the local projects in my open source class was successfully merged after a few days of review. 🎉

Project 👩🏻‍🏫

The issue I was working on was part of the Telescope project, which is a tool for tracking blogs in orbit around my college's open source involvement. Basically, it collects all latest blogs written by the faculty and students and displays them on a single page.

Issue 👀

This issue was initially created as part of the series during the previous month for Hacktoberfest. It related to the bigger issue which allowed students to add different translations to Telescope's documentation.

At first, I was not sure, but one of the reviewers mentioned that they can review Russian language and as I am trilingual, I decided on work on it. So, I requested the language and was assigned a corresponding issue.

However, during Hacktoberfest, I made enough pull requests and did not have time for this specific issue as I was caught up with my other assignments. So, now, when I finally have a chance, I have decided to go back to it and finish the job, as I personally believe that it is bad to leave dedicated issues behind.

I also checked out the other language translations which I can partially understand such as Ukrainian as a reference to my work. I noticed that some of the pages were different by language and realized that the produced Docusaurus translation page was a little outdated compared to the current overview page. So, I copied the newest version manually and translated it instead.

Translation 🪄

The task was to translate the overview page of the project's documentation.

This translation was more complicated than the previous ones but also more interesting. It required me to deliberately think and research some translation options, as the text contained lots of technical terms, formal wording and literary components. It was especially hard sometimes to choose the right wording, as Russian is a very rich but differently built language, and some of the words either do not have a perfect translation or have too many possible versions which are not exactly same. Also, some of the technical computer science terms either cannot be translated, as they did not exist in the language before, or have ridiculous new translation which no one uses and I did not even know about before doing some research. Additionally, all of my previous translations were smaller in size compared to this one.

Pull request review 🔎

After I was sutisfied my translation, I submitted a pull request. I messaged the reviewer in the pull request through comments, but did not get a reply for a day, so I decided to leave a kind message through the Slack channel with a request to check out the changes whenever possible. I made sure to thank the reviewer afterwards, as the translations are tricky sometimes, especially with Russian, so the suggestions are very valuable.

I received two reviews and multiple suggestions around different possible wordings. I implemented the changes and waited for them to be approved. Later, I saw my pull request being merged.

Conclusion 💡

Now, I know how to translate different technical IT terms into one of the languages I know and how to work with internalization in Docusaurus documentation. Valuable and interesting experience overall.

Reviewing PRs

Gulnur Baimukhambetova — Fri, 18 Nov 2022 23:27:59 +0000

Hello everyone! 🙋🏻‍♀️

Today, I reviewed multiple Pull Requests that were made to our internal class projects. I wanted to contribute to one of the newer ones, so I decided to start with Seneca's VSCode extension. Plus, I really liked the idea of what it can become.

1️⃣ First pull request

Link: https://github.com/Seneca-CDOT/vscode-seneca-college/pull/13

The first pull request that I found was made by @IvaniGabrovsky and it included changes related to the creation of the CONTRIBUTING.md and README.md files.

CONTRIBUTING.md's purpose is to have instructions for the contributors and an overview of the project to help them get started with the changes. Meanwhile, README.md's primary audience are the users and it should tell what the tool is, how to use it and any additional helpful info. It also serves as the first stop point when learning about the project.

Ivan made a great job, however there were many places for improvement, some of which were already outlined by the professor, @humphd, and another student, @SerpentBytes.

I decided to still take a look. I started a review after giving my first comment and ended it with the request for changes.

I focused on multiple areas such as:

grammar, as these files represent the project and cannot have big grammar mistakes (influences reputation);
wording and content, as I have read through many similar files for other projects, I can tell what are some important steps and can give suggestions;
guide for other comments, as Ivan sometimes asked for help through personal messages, I wanted to guide him where I can and give some recommendations for previously mentioned issues.

Ivan responded to every suggestion very quickly and made all corresponding changes.

2️⃣ Second pull request

Link: https://github.com/Seneca-CDOT/vscode-seneca-college/pull/12

I continued to review pull requests in the same project and found this one, which was made by @P-DR0ZD and focused on setting up Gitpod for the project. It created main Gitpod files and added information about Gitpod setup to the README.md.

First, I had to research about Gitpod, as I do not have much experience about it and in order to test it I need to figure out what is expected. After some googling and looking through its documentation, I figured out that it allows to setup development environments to work on the projects online which is very helpful to get contribution going.

First, I check the link provided in the new README.md file and it worked perfectly. I could open VSCode through Gitpod and the project would be automatically prepared for me.

I also checked out new Gitpod yaml configuration file which looked good to me. I think it was prebuilt by Gitpod, so no possible syntax mistakes.

However, I had one suggestion. I looked through the documentation for .gitpod.yml and noticed that they have support for VSCode extension recommendations. I also went to .vscode/extensions.json in our project, as it is where recommended extensions would usually be specified, and found one - "amodio.tsl-problem-matcher". So, I suggested to include it for Gitpod as well.

Overall experience 🙌

Overall, it was very helpful experience to get on the other side of pull requests. I learned about new tools and used my existing knowledge from my previous experiences to help make more qualitative changes.

Continuous Integration for Node.js project

Gulnur Baimukhambetova — Fri, 18 Nov 2022 21:38:11 +0000

Hello everyone! 🙋🏻‍♀️

Today, I wanted to share how to implement continuous integration in a few easy steps using Github Actions.

In the previous post, I was telling how I added the tests using Jest framework to my SSGulnur tool. This will be a continuation, as we will use these tests as a step in Github Actions workflow.

Steps 🙌

Basically, I followed this little step-by-step guide by Github and made a few configurations to match my workflows needs. Below, I will explain it in more detail.

I navigated to my GitHub repository, clicked "Actions" tab and chose to create a new workflow, where I was presented with different kinds of starter workflows. I chose the one for Node.js, as it is what my tool is using.

This will create a configuration yaml file in your .github/workflows folder which will explain Github what and when to do to your repo changes.

I changed a few lines to match my scripts for linter and tests and this is what I ended up with:

# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs

name: Node.js CI

#will work on every push and pull request to the main branch
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v3
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci #runs clean installation
    - run: npm run lint #linter  
    - run: npm test #run tests

I then committed this to my repo and checked the "Actions" tab for the successful run. I also made an intentional mistake to double check that my workflow will fail if something is wrong, and changed it back.

Unrelated but also experience 😁

Today, I also reviewed and added a few tests to another project, which was a similar tool of my friend. I was a little happy when I realized that I have structured my work in an easy way for testing such as I have lots of isolated small functions. Meanwhile, my friend had to copy his main function and rewrite it to be able to test its logic. It was a little confusing at first to figure out how everything works and to find something testable, but because he was also using Node.js and Jest, it was manageable.

Also, while reviewing each other's pull requests, we learned a valuable lesson on how to make reviews and request changes, which was a very fun experience.

Conclusion 💡

Apparently, CIs can be very easy if you already have your scripts set up and can use one of the starter workflows.

JavaScript testing with Jest

Gulnur Baimukhambetova — Sun, 13 Nov 2022 09:42:54 +0000

Hello everyone!

Today, I added testing to my SSGulnur project.

Jest 🃏

I chose Jest, as it is one of the most used testing frameworks for JavaScript and most of my tool's logic is written in JS. It was developed by Facebook and is open-source. Jest also has CLI option for checking coverage which is very great, it shows which lines of code have been tested and not and prints a beautiful report.

Set-up 🙌

Working with Jest is quite easy even for beginners (thanks to their well-written documentation).

First, I had to install it in my project. Can be done by running:

npm install --save-dev jest

Then, I added the following scripts to my package.json to be able to run then through npm:

 "scripts": {
    "test": "jest --",
    "test:watch": "jest --watch --",
    "coverage": "jest --collect-coverage --",

I also updated my CONTRIBUTING.md, so the future contributors find instructions for testing.

The Jest Framework is used for testing in this project.

You can use the following commands:

'npm test' for running test
'npm test example-test' for running only the tests that were specified with a pattern or filename (e.g. npm test createHTML)
'npm run test:watch' for running tests related to changed files based on git (uncommitted files)
'npm run coverage' for checking the coverage of the tests

First unit tests 🥇

Unit tests allow to check a small pieces of logic independently. I had to restructure my code by breaking it into even smaller pieces so that I can work with more focused functions.

I added test folder to hold all my sample test files and tests. I used the snapshots to check if the output of the functions is as expected, because I work with big HTML files which would be hard to program manually.

Here is my test file:

const { createHTML } = require('../../src/helper');

describe('createHTML', () => {
  test('.md files have to properly transform into HTML', () => {
    expect(createHTML('test/sample.md')).toMatchSnapshot();
  });

  test('.txt files have to properly transform into HTML', () => {
    expect(createHTML('test/sample.txt')).toMatchSnapshot();
  });

  test('Style should change if given with .md file', () => {
    expect(
      createHTML('test/sample.txt', 'https://cdn.jsdelivr.net/npm/water.css@2/out/water.css')
    ).toMatchSnapshot();
  });

  test('Style should change if given with .txt file', () => {
    expect(
      createHTML('test/sample.txt', 'https://cdn.jsdelivr.net/npm/water.css@2/out/water.css')
    ).toMatchSnapshot();
  });
});

Conclusion 💡

I am a newbie in testing and before it would get me very frustrated, as I used to think that it was a lot of unrewarding manual work. However, now, I understand its importance and learn about it more and more. Apparently, it is also not that hard to start. 😊

How to beautify your code and make contributions easy?

Gulnur Baimukhambetova — Tue, 08 Nov 2022 23:53:28 +0000

Hello everyone! 🙋🏻‍♀️

Today, I learned about Static Analysis tools which work on increasing the quality of your source code from the formatting and styling perspectives and by identifying bad coding practices.

I added multiple tools to my SSGulnur project and below I will explain why they you probably need them too.

Code formatters 💄

In open source, most of the projects use automatic source code formatters, beautifiers or "pretty printers". They make contributing easier, as they keep the source code in a consistent format.

I am using mostly JavaScript, so my obvious choice was Prettier. For most of the formatters, the steps are similar such as you would have to:

read through the documentation to install and setup the tool,
configure the rules and options to customize the look, e.g., .prettierrc
create an ignore file to exclude files from formatting, e.g., .prettierignore,
(optional but great to do) create a script to run the formatter in one command, e.g., npm run prettier defined as a script in package.json .

Linters 🕵️‍♂️

While contributing to a project, the least a develop wants to do is add code full of little bugs and bad practices. Linters help with that problem by scanning the sources code and identifying syntax errors, adherence to coding standards, security bugs and other potential errors.

For my project, the best choice is ESLint as it is widely used. The steps are very similar to adding a beautifier.

Editor 📠

The same way we configure our local editors, we can also pre-set the IDE settings for everyone who downloads the project. In VSCode, you can configure workspace setting which override the user's settings. Also, VSCode has lots of extensions and the ones for Prettier and ESLint which make the development much easier. There is a way to set extension recommendations for a workspace.

Pre-commit hook 🛃

Additionally, there are pre-commit hooks which can be setup to seamlessly validate and modify the source code before every commit. I followed Prettier documentation to create one. I ran npx mrm@2 lint-staged which installed husky and lint-stagedand added a configuration to the project’s package.json. Then, I modified the commands a little and that's it.

CONTRIBUTING.md 📜

Creating a CONTRIBUTING.md file is very important if you want other people to contribute to your project as it will be the first stop guide which should explain how to choose issues, set-up a tool, test it, any conventions and other development instructions.

Conclusion 💡

Let the tools do the work for you!

Ps:

Yesterday, one of my classmates shared an interesting article which encourages people to blog and brings up a few blogging ideas. The author, Simon Willison, believes that one of the best topics to chose is TIL which means "Today I Learned". It reminded me so much of all these posts which I used to start with "Today, I explored/tried/coded/learned/etc.". However, before my article name convention was "My first " + topic name. Recently, I realized that what I write is much more meaningful than "just my first experience", so I should not limit the name. From now on, my blogs will most probably start with "How " + my actions. They will not be fully detailed documentations but should describe the main ideas around the topic and steps.

Docusaurus first impression and stealing like an open sourcer

Gulnur Baimukhambetova — Mon, 31 Oct 2022 21:36:48 +0000

Hello Everyone!

Today, I am going to share a new cool tool I learned about from my professor as well as the new changes that I did to my SSGulnur command-line tool.

Docusaurus 🦖

Today, I explored a new tool called Docusaurus. It was created by Facebook and is now part of the Meta Open Source. Docusaurus helps to create beautiful documentation websites for open source projects with no need of web knowledge, so that the users can focus on the content instead of implementation. It is full of additional features, very easy to use and therefore is very popular and widely used. One of the open source tools you are using has definitely built its documentation with Docusaurus. For example, React Native, Jest, Home Assistant are all using it.

Experience ✨

I decided to check out Docusaurus myself and created a sample website. I followed the Docusaurus documentation and its installation instructions. I did a mini 5-minute tutorial and decided to deploy my website. At first, it was hard as I tried to do it all manually myself, but then I found these amazing deployment docs (which always existed, but I am a lazy developer who's hands type code before checking the docs 🚩). Apparently, it only required one command lol.

So, I would confirm that this tool is so easy to start and use.

You can see my sample repo and live GitHub Pages website at https://gulyapulya.github.io/docusaurus/.

Stealing like an open sourcer 🥷🏻 he-he

Docusaurus does something similar to my SSG tool which is converting different types of files to html static pages. However, it does it much better and is full of cool features which I am very tempted to duplicate.

I recently found out that in the open source world, you can copy from each other as long as the license lets you to. Docusaurus uses an MIT license which allows you to "use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software," as long as you continue the license.

SSGulnur's new feature 👀

Previously, I was required to implement the markdown support manually which meant that the use of public libraries was prohibited. My tool could only support limited styling elements such as header1, header2, links, bold and italics, but now I can finally let my tool have a full markdown support by using Showdown.

I chose this feature as it seems foundational to me. Other features such as different themes, improved accessibility and configurable sidebar are nice to have but less important than the markdown support.

I filed a new issue and started working on it on the new branch. I saved every step as commits which I squashed into one later. Everything went as planned and the implementation took me about what I expected, as I was not creating anything new myself and was only working on integrating an existing tool into my project.

New feature always means new issues 🤡

However, when I started testing, I realized the tool works but there were still many places for improvement. For example, there is a bug, which probably existed before but I never noticed, that the last paragraph would not get converted and pasted into resulting page. Additionally, I filed an issue for documentation improvement as I did not update it to reflect the full markdown support.

As I am a lover of Agile, I try to embrace progress over perfectionism. So, I filed those improvements as issues to work on later. The most important to me was that the tool worked and general purpose was achieved.

Conclusion 💡

In open source, we aspire to inspire!

Hacktoberfest Experience Wrap-up and Tips!

Gulnur Baimukhambetova — Wed, 19 Oct 2022 22:14:11 +0000

Hello everyone!

Today, I got my fourth pull request accepted as part of the Hacktoberfest and I wanted to share a few details about my experience and give some advice to anyone who is still participating.

Experience

This was my first time ever Hacktoberfest and I learned about it from my open-source course professor, David. At first, I was a little scared and worried as I was also a newbie in open-source. I was not sure if I could complete four contributions to other companies' or people's projects in such a limited time. However, I used that anxiety in my own good and started my research early. A few days before October even started, I started looking for the issues to work on or projects that I might get interested in. I wanted to start from something small and progress slowly to give myself time to get confident. Overall, everything turned out even better than I expected and now I have already done the required amount of PRs accepted although it is still the middle of the month.

By the way, you can find more details about my contributions during this month in the previous posts.

Learning outcomes and tips

I learned a lot during these a few weeks and I wanted to share some of my important conclusions:

First and foremost, open-source community is very welcoming!

So, never be scared to start or ask questions. No one is going to laugh at you or punish for asking for clarifications.

Everyone can and should contribute to the open-source and every contribution is important!

Even if you are not a technical person or do not have much of coding experience, there are a lot of issues that only require writing skills such as working on documentation or translations.

If you are not sure if the issue is too hard for you, you can ask the maintainer for more details or even their opinion.

Communication is key! Always stay polite, concise and kind.

If you found an issue that is of interest to you and it looks taken but here have been no updates for a long period of time, you can always ask to double check if the person is still working on it. If not, you can comment to let others know that now you will be working on it.

Activity varies a lot, some projects or PRs are slow and some are faster, so it depends a lot on the project or change.

So before picking an issue, analyze the repo and plan accordingly:

How fast people reply to issues questions or to the submitted PRs.
How many ignored or forgotten PRs they have (if it goes back to 2015, this is a red flag)
How many contributions or contributors they had
Are there clear instructions or the contributions document (usually called CONTRIBUTING.md)

Networking helps or as my prof says leverage the community.

Join different Slack or Discord channels. Some projects might have links to their channels where you can meet other contributors and ask for help. Hacktoberfest also has their official Discord channel so you can join it to find repos to work on, community and support.

As a first timer it is alright to be lost and scared, but do not worry, you will definitely figure it out.

Some tips for my newbies would be to:

Start early. Research and start looking for issues early to give yourself enough time. You will thank yourself later for that.
Learn Github advanced search. Here is a Github doc on how to search for issues, but your main friends would be is:issue and is:open to look for open issues, label:Hacktoberfest and sort:comments-asc to view all Hacktoberfest issues with least comments, as well as user:Microsoft if you want to filter a specific account or company. Here is a sample Url that you can use.
Search online for issues or repos. Sometimes you may find good issues or repos from owners' blogs. For example, this post by @cicirello mentioned that they are looking for translation contributions. You can also look for #contributorswanted tag inside the blogs.
Search online for tips on contributing. I once landed on @sylwiavargas post about how to contribute to the projects' documentation and she made it so easy. There are so many tools and workarounds that you need but just do not know about yet. So, start looking!

Discussion

I wanted to ask if anyone has other useful tips that I did not cover. Let's share and help each other complete this Hacktoberfest successfully and prepare better for next one!