How to make your Github README.md readable

github-octocat

Readme file in GitHub is essential and very useful for everyone to get involved in the code , whether its an open source project , or a team project .

Github helps you to create readme file once you start a new repo , but there are few things that needs to be added in order to make look good and easy to read .

The table here will highlight few tags that can be used once you write your readme file

Tag Description
”’ you add it to the beginning and the end of a code block you add add the word python or javascript after (”’) to add colors to the code.
# you use this tag once you want to add a heading text.
* you can use it once you want to add bullet points.

 

here is a detailed screenshot in a readme file for the previous listed tags

Screen Shot 2017-12-29 at 8.31.58 PM

 

and this is the result

 

Screen Shot 2017-12-29 at 8.32.20 PM.png

 

Enjoy!

How to use Continuous Integration with Python , Github and Travis Ci

travisci-mascot-1

 

Travis Ci is a popular tool to apply Continuous integration , such saves you so much time when you try to test your code a specific requirement , that you can define .

 

I have used travis with Python so in this short blog I will explain how you can easily use it and get around few obstacles that you might face during the setup .

 

First , have your repo in GitHub , so push the repo that you want to GitHub , after that login using the your GitHub to travis ci , and the website is :

https://travis-ci.org

 

Screen Shot 2017-12-24 at 7.15.48 PM

 

you can add new repo once you click on the plus sign there next to my repo.

 

in order to test in you need to add a new file to your repo the file name should be : .travis.yml

This file should include your testing requirements I have used with python so I will explain the elements in the file along with description

 

Screen Shot 2017-12-24 at 7.22.12 PM

 

Line 1 : you set the language that you wanted to be tested .

Line 3 and 4 : specify the version of the language that you want to be tested , I have tested my code in version 3.2

Line 6: if you have special requirements should be included in the installation , for this I have the requirements.txt file empty .

Line 8 : run the code , as you may know to run a python file you need to write python and sometimes python3 based on your setup .

 

One important thing is to ensure your code doesn’t need your interaction means it can run with you putting inputs, so it can run on its own till the end .

 

A successful running code will give you a green colour indication that you code has been executed successfully .

Screen Shot 2017-12-24 at 7.26.53 PM

 

A job log screen will look like this

Screen Shot 2017-12-24 at 7.28.27 PM

 

at the end of the execution you should be getting this message at the end  if you are using python 🙂

 

Screen Shot 2017-12-24 at 7.28.35 PM

 

I hope this tutorial is useful ….

 

Enjoy and Happy Holidays

Getting started with Python

 

python_sh-600x600

 

Python is one of the most popular programming languages , and it has been ranked number 2 in some statistics of most popular language in Github .

 

Python very friendly and reminds me of C , very easy to use due to its loosely typed syntax .

 

Python can be used everywhere , in Web using popular frameworks like Django , or as a Desktop application and also you can use it to develop android applications.

 

In this blog i will be going though some basics to get you started with Python .

Python can be used from the terminal without creating a file or compile it , and its very nice feature for quick testings .

the example below shows how you can actually run python from the terminal without creating a source code and compiling it.

example_final.jpg

As you can see we have create two variables and we have assigned them with numbers , and we have specified any data-types .

After that print (a+b) will some the 2 variables and printout the result .

As you can see its very easy to learn and very flexible to work with .

Enjoy!

 

 

 

MongoDB … Quick Start

mongodb-logo-rgb-j6w271g1xn

Intro

Mongo DB is Non relational Database , that means it doesnt use joins which known in the relational SQL databases .

MongoDb doesnt use tables , instead it uses whats called a document . MongoDB uses reference instead of joins once we try to link two different documents .

 

Advantage

Mongo Db is very easy to be modified , so for that it has better scalability and better performance .

 

Syntax example for update

lets assume that we have the following document

User Schema

{

first: “Hadi”,

last: “Saeed”

}

 

User Schema

{

first: “Hadi”,

last: “Saeed”

number:”1234-567-890″

}

 

So whats the different between collection and document ?

 

A document -> part of the collection , and they look like JSON object .

A collection -> a group of MongoDB document , all documents in the collection they have similar or related purpose .

 

Syntax example :

create a document

 

Create_document

the keyword use creates a document in case this document has been created you will switch to be using this document .

 

Inserting

Screenshot from 2017-11-24 21-06-16

very similar to JSON as you can see key and value .

 

List

pretty

we can use pretty to group listing which makes it easy to read , otherwise we can just use find to see the list of items inserted in the document .

 

update

 

update

we use update() to update the item in the table we can search the exsiting item by name or other unique identifier.

Atom and github integration

 

We all know that Atom is a GitHub editor and we all know by now that GitHub is an essential tool to work in project and collaborate with others .

 

Here in this blog I will be showing few things that can help you to work with both GitHub and Atom .

 

once you start your repo in you local machine you will be able to see .git in the project folder :

Project folder in Atom

 

You will be able to notice the changes that occur in your repo in terms of what files have been modified or added .

 

Added files and changed file in the repo . “Atom project folder”

 

As you can see above the modified file is yellow coloured , and the green coloured files are recently added .

** Note : the colors and the behaviour of the changes might change based on your theme , I do implement a custom theme in my Atom setup .

 

Changes in lines

 

On the right side of the editor just before the line number you can see a vertical line in yellow , this line indicates where these changes , again it might differ based on your theme.

 

Finally the command from Github that you can use in Atom :

 

Github commands

 

This is pretty awesome feature in Atom , pressing the command : Command + Shift + P

will  provide you a drop list where you can do various things in it , I did type git in this list and from there you can see you can perform pull , push fetch and more .

 

This is a short blog for how to work in both Atom and github , and I hope you do find it useful.

 

 

Contributing to Mozilla Pontoon

Pontoon is an interesting project from Mozilla , I have done a blog for how to install and what you can use it for .

Since its an open source project , the source code is available via GitHub :

https://github.com/mozilla/pontoon


As a contributor you can help in make this product better by one of the following :

1- contribute as a localizer/translator .

2- contribute in fixing bugs .

 

To contrubite as a localizer , you can follow this link :

https://pontoon.mozilla.org

Create an account and you will be able to suggest strings to projects .

you can see the completion level and how important “priority level” of the project by visiting this :

https://pontoon.mozilla.org/projects/

Screen Shot 2017-10-10 at 1.49.30 PM.png


The other way you can contribute to Pontoon by fixing bugs , and the list of bugs are available in bugzilla and you check it out from here :

https://bugzilla.mozilla.org/buglist.cgi?component=Pontoon&product=Webtools&bug_status=__open__

 

you will have to contact the admins of the project to assign you to the bug and they will help you out with it , the team very helpful and cooperating  (Thank you Matjaz!) .

The screenshot below to shows the bug i have worked on :

Screen Shot 2017-10-09 at 10.33.33 PM.png

 

After that ensure that you clone the project from GitHub , and ensure you follow the contribution guideline you can find all the information here :

https://mozilla-pontoon.readthedocs.io/en/latest/dev/contributing.html


few things to keep in mind :

1- Create a branch for the bug that you are working on in your local repo .

2- run the testing locally since once you do pull request the code will be checked via

https://github.com/travis-ci/travis-ci

3- Pontoon is written in Python , so you should be familiar with Python and Django framework.


I do following these steps in order to test my code :

1- ensure you are running the virtual environment which is :

virtualenv venv
source ./venv/bin/activate

this is mentioned once you run pontoon in your local server and you can read more about this in the installation page for Pontoon .

2- run pylama  command which will check for the code conventions .

pylama pontoon


once you do pull request and your branch for the bug passes the testing , and the code satisfy admin , your code will be merged . You may receive comments to change certain things in the code by the admin before they merge your code .

Screen Shot 2017-10-10 at 2.06.04 PM.png

 

Its very interesting experience , and actually you will be enjoying working on it .

 

 

Getting started with Mozilla Pontoon

Screen Shot 2017-10-04 at 9.27.50 PM

 

Mozilla Pontoon is an open source tool that helps people to localize software or online products which follows the international localization format (read more).

 

People can contribute to this project by fixing bugs or translating strings .  In order to fix the bugs in Pontoon you will have to install it locally in your computer , keep in mind that Pontoon bugs are listed in BugZilla – Click here to see the list .

 

I have installed Pontoon locally using a Linux machine , you will have to through the steps which can be found here – click here 

Few important things I need to point out , once you close the terminal you will have to set the docker environment every time you open the terminal .

The point number 5 in the installation manual wasn’t very clear for me so you will actually have to create a file called .env and insert the information listed below .

 

It took few attempts to make it work and really I had to close the terminal and rerun the virtual environment and then run the command in the step number 6 .

Code : from pontoon installation page

  1. python manage.py migrate
    

 

if you have followed the steps correctly you should have something like this :

Screen Shot 2017-10-04 at 9.43.44 PM.png

 

once you complete the installation you will be able to run from localhost as shown below:

works.png

Getting started with Atom

Selecting an editor is sort of commitment and it will help you to have a faster progress and motivation to get things done .I’ve used several editors “Vs Code and sublime” lately and I have selected to work with Atom for various reasons ; some of those reasons are Atom is built by Gitub and Github become an essential tool these days whether you are working in a group or contributing to remote projects or just to see yourself progress ,another reason its very light and there are many ways you can customize this to work the way you want based on the packages that you install online  . This doesn’t mean the others are bad but just its a personal preference .

 

Atom is easy to use you get two panels once you start a new project , the left panel get you the list of files in your project and the right side your coding section with ability to have multiple tabs for each file you are coding .

 

Screen Shot 2017-09-27 at 8.57.55 PM

Atom editor

 

another feature that I really like is the amount of themes that are available online . You can select your desired theme from multiple sources , I do find this website very helpful :

http://atomthemes.io

I’ve personally selected the Material UI since I’m in the UX/UI realm .

Screen Shot 2017-09-27 at 9.08.41 PM

Atom editor settings

 

In order to install this I had to run the command line and put the following :

 

Screen Shot 2017-09-27 at 9.08.56 PM.png

 

after that from the preferences in the editor you can choose it from the drop down list and you can easily switch between themes from that list.

 

change_theme

switching themes in Atom

 

Once  you create a file and save it with the language file extension atom will colour code it  automatically .

Screen Shot 2017-09-27 at 9.00.01 PM

 

The amount of packages in Atom is really countless , and how useful they are will depend on what you are working on , for example I do UX/UI and I do need something that help me in color and design , and the package color-picker is really useful , since all what I need to do in order to select the desire color and have the right values “Hex or RGB” CMD + Shift + C   (MacOS) and a color picker will pop up to select from as you can see here

COLOR_PICKER.gif

Atom color picker package

 

As we can see there are really good features that will help developers to set up a productive environment which will help them to achieve their goals faster .

 

Installing Firefox build on MacOS

Fun experience that would require multiple attempts in order to create a successful build .

ensure you have the following to have a successful build

install python

install rust  “link below”

https://www.rust-lang.org/en-US/install.html

** Important **

Once you build using Artifact Mode  ” image below”

Screen Shot 2017-09-20 at 9.00.48 PM

Most likely you will be getting this message :

Screen Shot 2017-09-20 at 9.00.59 PM

if you get this message just re-run /.mach build and select the 2nd option which is Firefox for Desktop , and it will proceed to the next step.

 

the process of the building Firefox took approx 48 mins and you might face an issue in compiling it most likely has to do with this file “‘wchar.h’ file not found, err: true”. I did face that and to solve this I had to run the following command since the problem had to deal with Xcode :

xcode-select –install

and it did solve the problem for me .

 

good luck!

 

 

Welcome to my blog!

This is my first post , and I will be posting mainly UX ,  and open source related topics .

I did search for couple of open source projects on Github , and I do find the web accessibility is a very interesting topic , and since I’m a certified UX designer I will be really interested in working with these kind of projects .