As an IT support officer, I can put myself in the perspective of a user and identify friction points, but this document had no visuals, no simplified explanations, just walls of backend jargon: service mesh, container orchestration, async queues, REST APIs… you name it.

I realized quickly: if someone like me struggles to understand this, so will PMs, frontend devs, new hires, and even other IT staff.

Here’s a practical guide for creating system architecture documentation that anyone on your team can read and use:

• Step 1: Show the System from Different Angles

• Step 2: Make Diagrams the Star

• Step 3: Translate Tech Into User-Relevant Outcomes

• Step 4: Make Communication Clear

• Step 5: Keep it Simple and Consistent

• System Architecture Documentation Tools for Teams

• Conclusion

Step 1: Show the System from Different Angles

A good architecture doc isn’t just a list of tech terms. Think about who is reading it:

A. Conceptual View (PM/UX/business folks)

• What the system does for the user.

• Example: “User Authentication System,” “Checkout Service”

• Focus on user value and business goals.

B. Component View (frontend developers/IT staff)

• How the parts interact.

• Example: “Web App calls API Gateway → Microservice → Database”

• Focus on data flow and system boundaries.

C. Operational View (backend/DevOps)

• Where the system runs and how.

• Example: servers, databases, cloud setup, scaling.

• Focus on infrastructure and deployment.

This way, everyone can find what’s relevant to their role without getting lost in technical weeds.

Step 2: Make Diagrams the Star

Words alone don’t cut it. Diagrams help people visualize the system, especially if they’re not experts.

Types of Diagrams to Include

• System Context Diagram: Shows the system and its external dependencies. UX/PM/IT staff can see how it touches users and other systems.

• Container Diagram: Shows main boundaries like “Web App,” “Auth API,” “Database.” Frontend and backend teams benefit.

• UML/Component Diagram: Shows internal structure or interactions. Mostly backend focus, but helps everyone understand flow.

Tip: Even a simple flowchart drawn in PowerPoint, Figma, or by hand is better than none. Clarity matters more than perfection.

Diagrams help:

• UX sees user impact.

• Frontend knows which services to hook up.

• Backend sees infrastructure and interactions.

• Everyone shares the same mental picture.

Example 1: System Context Diagram

This diagram illustrates who uses the system (a person on the web) and which external services it depends on, like Stripe for payments and SendGrid for emails. It doesn't show the internal workings of the system, just what it connects to.

Example 2: Container Diagram

This diagram illustrates the main components of the system: the Web App, which is the user interface; the Auth API, responsible for handling login and security; and the User Database, where user profiles are stored. The arrows indicate how these components interact with each other.

Practical Tip: Tools to Create Clear Architecture Docs.

Step 3: Translate Tech Into User-Relevant Outcomes

System architecture goes beyond databases and queues, focusing on making the product fast, reliable, and secure for users. Link technical requirements to outcomes everyone can understand:

Even a person with basic UX awareness can see why tech decisions matter.

Step 4: Make Communication Clear

One major source of confusion is how different parts of the system talk to each other. Spell it out:

a) Frontend ↔ Backend: Clearly explain how your frontend connects to the backend.

Example: “The website sends login requests to the Auth API.”

b) Backend ↔ Backend: Explain whether services communicate with each other instantly (synchronous) or through background tasks like message queues (asynchronous). This helps the team understand why some actions feel instant to users, while others take time.

Even non-backend readers can follow the flow and understand how it impacts the product.

Step 5: Keep it Simple and Consistent

• Use headings, bullet points, and a table of contents. Don’t write a novel.

• Keep names consistent: “User Service” in diagrams should match text labels.

• Explain the “why” behind major decisions:

“We chose a NoSQL DB for User Profiles because it requires fast read/write for non-relational data.”

Consistency and simplicity make the doc useful to everyone, not just backend experts.

System Architecture Documentation Tools for Teams

Great architecture documentation lives where your team already works and uses tools that are easy to update, share, and understand. Below are the common types of tools teams use, grouped by purpose.

Documentation Platforms (Where You Write the Full Doc)

You can use these tools to combine text, diagrams, and structure a document.

Google Docs
Simple, familiar, and collaborative. Supports real-time comments, edit history, and easy sharing. Perfect if your team already uses Gmail or Drive. Just paste diagrams as images.

Confluence
Common in larger companies. Integrates with Jira, supports page templates, and lets you embed diagrams. Good for structured knowledge bases.

Notion
Flexible workspace for small teams. Mix docs, tasks, and diagrams in one place. Great if your team uses Notion for other work.

GitHub/GitLab Wikis (with Markdown)
Ideal for engineering-heavy teams. Docs live next to your code, and you can include diagrams using simple code (like Mermaid). Changes are tracked like code.

Start with Google Docs if you’re unsure. A living doc people actually read is better than a “perfect” one no one opens.

Diagramming Tools (Where You Create Visuals)

These help you draw the architecture diagrams you’ll add to your documentation platform.

Draw.io
Free, browser-based, and drag-and-drop simple. No sign-up needed. Exports clean PNG/SVG files you can paste into Docs or Confluence. Great for C4-style diagrams (System Context, Container, and so on).

Figma
If your team already uses Figma for design, you can create architecture diagrams using basic shapes and arrows. Real-time commenting makes feedback easy. Just export as PNG for Docs.

Mermaid (Diagrams as Code)
Write simple text like User --> Web App, and it becomes a diagram. Works in GitHub, GitLab, and tools like Obsidian. Use the Mermaid Live Editor to design, then download and paste into Google Docs.

A Key Insight from Practicing Architects.

Avoid tools that only produce static images (like PowerPoint, Canva, or basic whiteboards) for anything beyond quick sketches. If the same service appears in three diagrams and you rename it, you’ll have to update all three manually, leading to outdated and inconsistent docs.

How They Work Together

1. Write your doc in Google Docs (or your team’s existing platform).

2. Create diagrams in Draw.io or Figma (or try Mermaid if you’re curious).

3. Paste the diagram into your doc, add alt text, and explain what it shows in plain language.

This combo gives you accessibility, collaboration, and maintainability without overwhelming you or your team.

Conclusion

You don’t need to be a senior engineer to write great architecture docs. You just need clarity, empathy, and the willingness to explain “why.”

I thought, “I’ll add it later.” But “later” never came.

Weeks turned into months, and my once-simple idea turned into chaos. A developer who joined my project had no idea how to set it up. Even I, the founder, started forgetting why I structured certain parts of the app the way I did.

What was supposed to be a few months of development stretched to nearly a year. All because I ignored one small file: the README.

In this article, you’ll learn how to structure your README file to show all the important information about your project. You can see what it’ll look like here: MybrandName repo.

Table of Contents

• The README File is Not Just a Formality

  • README Structure

• MyBrandName — AI Branding Assistant

  • Features

  • Tech Stack

• Quick Start

  • Prerequisites

  • Installations

• Repository Structure

  • Architecture Overview

  • Example API Endpoints

  • Authentication (Supabase)

  • Environment Variables

  • Testing

  • Continuous Integration (CI)

  • Versioning & Changelog

• Contributing

  • Code of Conduct

• Deployment

  • License

  • The GitHub Repository

  • Developer Checklist

• Common Pitfalls & How to Avoid Them (Beginner-Friendly)

  • Problem: Hardcoding API Keys

  • Problem: No Quick Start Section

  • Problem: Missing Example Requests or Screenshots

  • Problem: Confusing Folder Structure

  • Problem: Forgetting to Version Your Project

  • Problem: No Testing Before Deployment

• 💡 What You Can Learn from This

• Final Words

The README File is Not Just a Formality

Many beginners see the README as optional—something you add just before submitting your GitHub repo. But that’s isn’t the right mindset.

Your README is your project’s map. It tells any developer (including your future self) where to start, how to set up the environment, and how everything connects. It saves time, reduces frustration, and turns a pile of code into a usable, understandable project.

If someone can clone your repository and get it running in under 10 minutes, your README did its job!

README Structure

Your README acts like the user manual for any developer who clones your repository. It should guide a developer to:

• Clone the repo.

• Install dependencies.

• Configure environment variables.

• Run both backend and frontend successfully.

• Understand how the system works.

Let me walk you through a sample README from a project called MyBrandName.

Here’s what the README looks like: https://github.com/nuelcas/mybrandname

MyBrandName — AI Branding Assistant

MyBrandName is an AI-powered platform that helps startups create a complete brand identity—logos, stories, and marketing assets—in minutes.

Features

• AI-Powered Branding – Instantly generate logos, brand stories, and marketing assets using OpenAI.

• Authentication – Secure user login and registration powered by Supabase.

• Database – Supabase for storing users, brands, assets, and subscription data.

• Frontend – Responsive UI built with TypeScript, Vite, and TailwindCSS.

• Backend API – Node.js + Express handles AI generation, authentication, and data management.

• Subscription Management – Stripe integration for plan upgrades and payments.

• Continuous Integration (CI) – Automated testing and build workflows via GitHub Actions.

• Versioning & Changelog – Semantic versioning with a clear project evolution record.

• Deployment Ready – Easily deploy frontend (Vercel) and backend (Render) with Supabase integration.

Tech Stack

• Runtime: Node.js + Express.js.

• Language: TypeScript.

• Frontend: Vite + Tailwind CSS.

• Database & Auth: Supabase (Database, Storage, Authentication).
  AI Service: OpenAI API (Logo, Story, and Content Generation).

• HTTP Client: Axios/Fetch API.

• CI/CD: GitHub Actions (Automated Testing & Deployment).

• Hosting: Vercel (Frontend) + Render (Backend).

Quick Start

Prerequisites

• Node.js 16+

• Supabase project (for Authentication, Database, and Storage)

• OpenAI API key (for AI-powered logo and content generation)

• Stripe account (for subscription and payment handling)

Installations

1. Clone the repository

git clone https://github.com/nuelcas/mybrandname.git

2. Install Dependencies

cd backend && npm install
cd ../frontend && npm install

3. Environment setup

cp backend/.env.example backend/.env

Update .env with your configuration:

• Supabase URL and API key

• OpenAI API key

• Stripe API key

4. Development

# Run backend
cd backend && npm run dev

# Run frontend
cd frontend && npm run dev

5. Production Build

npm run build
npm start

Visit: http://localhost:5173

Repository Structure

/mybrandname
├── /frontend
│   ├── /src
│   │   ├── /components        # UI Components (AuthForm, Navbar, etc.)
│   │   ├── /pages             # App pages (Home, Dashboard, Pricing)
│   │   ├── /hooks             # Custom React hooks (useAuth, useLogoGenerator)
│   │   ├── /lib               # Config files (Supabase, API client, constants)
│   │   ├── /styles            # Global and component styles
│   │   ├── App.tsx            # Main routing setup
│   │   └── main.tsx           # React entry point
│   ├── public/                # Public assets (icons, logos)
│   ├── tailwind.config.ts     # Configures Tailwind CSS settings
│   ├── vite.config.ts         # Contains build and development settings for the Vite bundler
│   └── package.json           # Lists frontend project dependencies, scripts, and metadata
│
├── /backend
│   ├── /src
│   │   ├── /routes            # Express routes (auth, brand, assets, subscription)
│   │   ├── server.ts          # Main Express server entry
│   │   └── config/            # Environment and DB configs
│   └── package.json           # Lists backend project dependencies, scripts, and metadata for Node.js
│
└── README.md

Architecture Overview

Frontend

• Built with TypeScript + Vite + Tailwind CSS

• Connects to Supabase for authentication, backend API for AI generation, and Stripe for payments

Backend

• Built with Node.js + Express

• Handles authentication, AI content generation, and database writes via Supabase

Supabase Tables

Example API Endpoints

Auth Routes

Branding Routes

Example Request:

POST /api/brand/logo
{
  "brandName": "NovaTech",
  "industry": "Tech",
  "style": "Modern Minimal"
}

Example Response:

{
  "logoUrl": "https://supabase.storage/novatech-logo.png",
  "palette": ["#121212", "#FF005C"]
}

Authentication (Supabase)

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_KEY
);

Environment Variables

Testing

Use Vitest/Jest for unit testing and Supertest for API routes.

npm run test

Continuous Integration (CI)

CI automatically runs tests when you push new code. This ensures your main branch always stays stable.

Example GitHub Action Workflow:

name: MyBrandName CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: |
          cd backend && npm ci && npm run test
          cd ../frontend && npm ci && npm run build

Tip: CI helps avoid “it works on my machine” problems.

Versioning & Changelog

Keep a CHANGELOG.md file documenting updates.
Use Semantic Versioning (MAJOR.MINOR.PATCH), for example,
1.1.0 → Added new features.

Contributing

We welcome contributions from developers who want to improve MyBrandName!
Follow these steps to contribute effectively:

• Fork the Repository

  • Click the Fork button on GitHub to create your own copy of the project.

• Clone Your Fork

  • Run:

    git clone https://github.com/nuelcas/mybrandname.git

• Create a Feature Branch

  • Keep your changes organized:

    git checkout -b feat/your-feature-name

• Set Up the Environment

  • Follow the setup instructions in the README to install dependencies and configure your .env files.

• Follow Code Style and Formatting Rules

  • Ensure consistent formatting before committing:

    npm run lint

• Use Clear Commit Messages

  • Follow the conventional commit style:

    • feat: – new feature

    • fix: – bug fix

    • docs: – documentation update

    • refactor: – code restructuring

• Write or Update Tests

  • Use Vitest or Jest for unit testing and Supertest for API routes.

  • Run:

    npm run test

• Document Your Changes

  • Update README.md, CHANGELOG.md, or CONTRIBUTING.md if needed.

• Submit a Pull Request (PR)

  • Push your branch and open a PR with:

    • A short, clear description of your changes.

    • Any related issue numbers (for example, “Closes #12”).

    • Screenshots or example outputs (if applicable).

• Participate in Code Review

  • Respond to feedback, make improvements, and help maintain project quality.

Code of Conduct

To maintain a positive and inclusive community, all contributors are expected to:

• Be respectful, kind, and patient when interacting with others.

• Welcome feedback and engage in constructive discussions.

• Avoid discriminatory or offensive language.

• Focus on collaboration and problem-solving rather than criticism.

• Credit other contributors where due.

• Report any violations or concerns to the maintainers privately.

Let’s work together to make MyBrandName a project where everyone feels valued and supported. 💙

Deployment

License

This project is licensed under the MIT License—see the LICENSE file for details.

The GitHub Repository

You can clone the GitHub repo, edit and build your app from it: MybrandName repo.

Developer Checklist

Think of this checklist as your final review before sharing your app publicly:

1. Supabase Authentication is Working

• Test your login and registration flow.

• Try creating a new account and logging in.

• Make sure the user’s data appears correctly in the Supabase “users” table.

2. AI Endpoints Return Proper Results

• Test your backend endpoints for AI-powered features (for example, logo generation).

• Use tools like Postman to send sample requests.

• Confirm that Supabase stores the generated data or files correctly.

3. Frontend is Responsive

• Open your app on a mobile device and desktop browser.

• Ensure the design adjusts properly to different screen sizes.

• Check for broken buttons, misaligned text, or hidden sections.

4. Continuous Integration (CI) Tests Pass

• If you use GitHub Actions, make sure your tests run automatically when you push code.

• Fix any failed tests before merging branches.

• This helps you catch bugs early.

5. Documentation Files Are Complete

• Ensure your README, CONTRIBUTING, and CHANGELOG files are up to date.

• Add setup steps, contribution guidelines, and update notes.

• This makes your repo beginner-friendly and professional.

Run through your README’s Quick Start section as if you’re a new user.
If you can set up the project in less than 10 minutes, your documentation is clear enough.

Common Pitfalls & How to Avoid Them (Beginner-Friendly)

Here are some common mistakes new developers make and how you can prevent them:

Problem: Hardcoding API Keys

Never store API keys directly in your code. If you push your project to GitHub, anyone can see them.

Solution: Store them in a .env file and add .env to .gitignore.

Problem: No Quick Start Section

If your README doesn’t explain how to install and run the app, other developers will be lost.

Solution: Always include a Quick Start section showing installation and setup steps.

Problem: Missing Example Requests or Screenshots

Readers want to see what your API or app does before trying it.

Solution: Add example API requests and responses (like the /api/brand/logo example). You can also include screenshots of the UI.

Problem: Confusing Folder Structure

A messy project makes it hard for contributors to navigate your code.

Solution: Explain your folder structure under “Repository Structure.” Include short descriptions of what each folder does.

Problem: Forgetting to Version Your Project

If you don’t track changes, it’s hard to know what was updated or fixed.

Solution: Use Semantic Versioning (1.0.0, 1.1.0, and so on) and keep a simple CHANGELOG.md file.

Problem: No Testing Before Deployment

Beginners often deploy without testing—and later find bugs in production.

Solution: Run your tests locally first. Automate them using GitHub Actions so that every code change is verified.

By addressing these simple issues early, you’ll build reliable, professional-looking projects that others can understand and contribute to easily.

💡 What You Can Learn from This

A good README file saves you from:

• Wasting hours debugging setup issues

• Confusing collaborators or testers

• Forgetting your own logic months later

It also makes your project look professional to employers and recruiters.

Final Words

When I finally embraced writing detailed README files, everything changed. New collaborators understood my projects faster. Deployment became smoother. And most importantly—I never had to “learn the hard way” again.

So if you’re just starting out, take my advice: Before you write your next line of code, write your README file.

But as this happens, questions arise, such as who supports these applications? And who will make the updates if there is a feature request or bug?

Many low-code applications are often created by a single developer, inherently leading to a single point of failure.

And don't let the advertised simplicity of low-code trick you into thinking anyone can edit the app, fix any issues, and add new features. Low code can still contain complexity, and complex solutions can quickly become a problem for organizations and teams that leverage dozens, if not hundreds, of other low- or non-low-code dependencies.

This doesn't mean that organizations should strictly restrict who can create these applications. Doing so would contradict the very purpose of low code. It's a model that empowers stakeholders themselves to rapidly prototype ideas and develop low-cost solutions to problems that, in traditional development, might cost millions of dollars.

In this low-code world, both organizations and developers need a plan. Developers, specifically, should have a plan to transfer knowledge of their products, whether working in a team or independently.

How to Simplify Complexity

Our relatively small team has created numerous low-code solutions, primarily leveraging Microsoft's suite of products. Some of these solutions are simple low-code canvas apps, while others contain hundreds of dependencies that are anything but low-code.

We've learned, sometimes the hard way, the importance of ensuring maintainability in our development. This means supporting the applications we build and enabling existing and new team members to support them in the future.

Initially, we found ourselves drawn to the premise of being able to create products that solve problems quickly. Before we knew it, we had our own problem: how do we support the array of these products, ensuring that not just us but new team members could do so as well?

Slow Down to Speed Up

This might sound contrary to the low-code paradigm, but taking frequent pauses to consider the long-term impacts of your decisions is critical to ensuring the tools you build today can be supported tomorrow.

This does not mean reverting back to the speeds of traditional software development, but you should not consider building low-code products as a race to the finish line.

Pair Programming

Incorporating traditional software development practices can significantly benefit the low-code movement. Even if your applications involve little to no conventional code, concepts like pair programming can be effectively applied when building low-code products.

Take, for example, the process of building a Power App. Traditionally, only one person could edit an app at a time. Although that limitation has changed—multiple people can now edit an app simultaneously—defining a collaborative process remains crucial.

Our team often employs a primary "driver" approach, where one member leads the development while another observes, providing real-time feedback and suggestions.

This method keeps everyone engaged and helps mitigate the effects of tunnel vision on the product. And this collaborative approach is especially valuable for more complex aspects of the application.

For more straightforward tasks, we often work in parallel but stay closely connected via Teams or Zoom, ready to coordinate and ensure each different component is part of a cohesive whole.

Application/Code Reviews

Low code doesn't mean no code. It is challenging to create robust applications with drag-and-drop alone. Even something like Power Apps has its own language called Power FX.

Schedule time each week to walk through or review others' applications to become familiar with their creations. Look for places where things can be improved, and be ready to accept feedback on your creations, too.

If you're using traditional code in your project, some of this can be accomplished with PRs. For purely low-code implementations, keep a document of changes and have a sign-off process to ensure other team members can access new changes.

For example, imagine adding a new screen to a Canvas app, allowing users to update personal settings. That change should be documented as unreviewed until at least one other team member has reviewed and signed off on this new feature.

Get Other Team Members Involved

If you're on a team, each product should involve at least two people to avoid single points of failure. Ensure each product has a primary and secondary developer or product owner. For larger teams, allow that secondary role to rotate, ensuring each member is more intimately involved with the team's products.

One way to get others involved and up to speed is to have other team members add new features or fix bugs in existing products under the guidance of the primary or lead developer. This knowledge transfer will help cultivate ownership in the various products your team supports, leading to higher engagement and motivation.

Additionally, as the workload is distributed more evenly across the team, bottlenecks are reduced, allowing for more expeditious handling of fixing bugs and enhancing products.

When a Hands-On-Approach isn't Possible...

Much of what I describe above is an attempt to get others involved with projects. The more we touch these things, the better we will understand them.

Inevitably, however, when this hands-on experience isn't possible, it is essential to have practices that can mitigate the effects of isolated development—that is, a development done by one or just a few people.

The two most important things we can do are create and maintain comprehensive documentation about our products and use standard practices as much as possible. We'll talk about documentation first.

Document, Document, Document

As you've probably experienced, the low-code movement allows applications to be created quickly. The more applications exist, the fewer touchpoints we have with older ones. While those touchpoints are critical to the knowledge transfer process, relying on them alone isn't enough.

Whether you're on a team or a solo developer, creating documentation that describes each aspect of your products is critical. For small projects, this may be a simple text document. For larger projects, you could utilize a SharePoint site. Of course, as products become even more complex, the various dependencies will likely have their own documentation (for example, Git repositories).

Here is an example of how you might document a product you are building:

Let's say you have an application that allows users to reserve a conference room for meetings. That application consists of a user interface (such as a Canvas app) and custom code that creates a follow-up reminder for the person who reserved the meeting a day before. This reminder could send an email to remind the user about the meeting, and if the meeting is no longer occurring, encourage them to cancel the reservation. Finally, this product could also have a reporting element, where administrators can see conference room utilization over time to better understand demand.

Here is how you might document this project:

1. Establish a single source of truth about this project, such as a SharePoint page.

2. This page briefly describes the project, the product owners, and the lead developers.

3. The page would also briefly describe this project's components (Canvas app, custom code, and reporting dashboard).

4. Finally, you would include documentation on any easy-to-overlook aspects or non-standard project implementations (more on standardization later).

The SharePoint page handles the high-level overview of the project and gets you pointed in the right direction. Regarding the individual components, the Canvas app will include comments and notes in the version history, and your custom code will leverage Git and often include a detailed readme.

Documentation can be challenging, but it is critical. While documentation should be comprehensive, it should complement the hands-on knowledge transfer techniques described above.

Standardize as Much as Possible

Whether it is low-code or traditional development, it is important to have standard practices. This is even more important when talking about low code because of the speed at which things can be developed and potentially get out of control.

From project planning, design, development, and testing to cross training team members, make time to create standard practices for each phase.

Standardization shouldn't be considered a way to eliminate the need for cross-training and documentation but rather a way to complement those stages and reduce the time needed in those areas.

If you can approach a problem the same way every time, you can spend time discussing those non-standard and easy-to-forget parts of what you're building.

Here are some questions to get you started:

1. What big-picture steps will each application require? Who will be involved in those steps?

2. What tools will you use? (for example, Power Apps, Appian, Pega)

3. Can you support traditional development? If so, how will that look?

4. What is your philosophical approach to development? For example, should you design the user interface or business logic first? What database will you use? (for example, SharePoint or Dataverse)

5. What conventions will you use in your code? (for example, naming conventions for screens and variables)

6. What does this knowledge transfer or cross-training process look like? Do you have dedicated times each week to review each other's work?

Of course, this list goes on. The more you learn, the more you'll realize what needs to be discussed. Get started by creating a Standard Operating Procedure (SOP), and be prepared to edit it early and often.

What if I am a Solo Developer?

If you're a solo developer, it may be easy to think that the recommendations above don't apply. But this couldn't be further from the truth. Creating and maintaining a knowledge-transfer framework is even more critical as a solo developer. While co-developing and pair programming are not directly applicable, the concepts still apply.

For example, take time to meet other developers and ask for feedback. At a minimum, it will be an excellent way to meet other people doing the same thing. And, of course, with AI taking a front row in programming, you can always leverage AI to help you learn new techniques and optimize the things you are building.

Finally, documentation and standard practices are just as necessary for the individual developer. First, if you ever work with others, you'll have a reference for your work. Second, these things will act as an external reminder of how you intend to solve development-related problems in the future.

Conclusion

While low-code platforms offer incredible speed and flexibility, they can also introduce challenges when it comes to maintenance. Rapid development, if not managed carefully, can lead to issues that undermine the long-term success of your applications.

But by intentionally slowing down and establishing a clear plan for knowledge transfer, you can safeguard the future of your critical products. This approach ensures that applications remain supported and sustainable, both now and for years to come.

Stay curious.

Found this helpful? I write about practical automation, productivity systems, and building smarter workflows — without the jargon. Visit me at brandonwoz.com.

If you're a web developer, designer, or project manager, you're likely quite busy these days and have a lot on your plate.

This is partly because the number of websites is growing rapidly, with 71% of all businesses in the world having one. In fact, every three seconds a site is launched!

So software development is a growing field, and developers have many responsibilities when it comes to creating quality websites and web apps. You have to keep up with changing trends while staying productive and organized. And you'll often find yourself working on multiple projects while collaborating with stakeholders.

But don't worry: you can boost your productivity and empower yourself and your team by using the right collaborative tools. In this article, I'll share some of my favorite such tools with you so you can start using them.

What are Collaboration Tools in Web Development?

Collaborative tools are software apps and platforms that help teams communicate, collaborate, track projects, and do collaborative coding. These tools ensure that team members will be able to work together smoothly, increasing productivity and helping them meet project deadlines.

Different collaboration tools, such as annotation tools, social media platforms, and version control, serve different purposes. They can help you and your team with task tracking or simply keeping everyone updated on the situation.

Some popular ones are GitHub for version control, Slack for real-time communication, Trello for project management, Google Docs for collaborative document editing, Jira for issue tracking, and Asana for task management.

How to Pick the Right Collaboration Tool for Your Needs

It can be challenging to pick a project management tool given all the available options. So here are some important factors you should consider before choosing a tool.

Verify Project Requirements

Consider the distinctive features of your project in order to determine what functions and features you need. Think about things like task management, code collaboration, communication, and integration of different tools when deciding which tool best suits your requirements.

You can also streamline various tasks using online tools. For instance at my company, we developed an online website builder which was a long-term project. Our design and developer teams used collaborative tools like Slack and Git to track progress and final deliverables.

Check Integration and Compatibility

Collaboration platforms should integrate seamlessly with your existing technology ecosystem. Ensure that the tools you choose are compatible with the development environment and programming language(s) you use.

You should also make sure that your collaboration tool works with any project management software you use, your version control system, and repositories to avoid errors.

For example, GitHub offers a version control platform that integrates smoothly with various development tools and services including project management platforms like Trello and Asana. It also provides continuous integration services like Travis CI and CircleCI, as well as code review tools like Codecov and Code Climate.

Choose User-Friendly Tools

Try to choose collaboration tools that are simple to use. Your tools should be intuitive and easily adaptable for users with minimal (or no) training.

The best collaborative tools create a good user experience and they should increase your efficiency and productivity.

For example, as a widely used messaging platform, Slack's intuitive interface and simple channel organization make it easy for web development teams to communicate in real-time and share files quickly.

Google Docs is another popular tool that almost everyone is accustomed to or uses. It’s very helpful in sharing written content or any other project documentation.

Consider Privacy and Security

Often, your team's projects under development are built based on confidential information and intellectual property. So you'll want to make sure that you choose the most secure tools, which include encryption and access controls. Industry standards are often a good bet.

For example, Jira is a popular collaboration tool for developers and offers options for cloud or self-hosted deployments. It also implements security best practices. Likewise, Microsoft Teams and Slack offer end-to-end encryptions that safeguard sensitive copyrighted and development information.

Scalability

The tool's scalability is another factor you should keep in mind. As your projects become more complicated, the tool will need to be able to handle such complexities. You might also need to add members to your team as it grows.

As an example, Hibox provides data privacy features, encrypted communication, and scalability for teams of different sizes.

Pricing

You'll want to compare the pricing and subscription plans of various collaboration tools before making your choice. It is important to consider your budget and the value each tool provides. As a result, you will be able to find the most cost-effective option that meets the needs of your team.

Some tools like Skype and Google Docs are free to use for everyone, but they might not fulfill your needs. You can opt for paid ones like Monday.com or Wrike which have a basic pricing plan of around $9 to $10 per month that may suit your needs. You can always upgrade to the Pro plan if the basic one is insufficient.

7 Best Collaboration Tools for Web Developers

Now you should understand the benefits of using collaboration tools and what to consider when choosing one.

Let's go over 7 of my favorite online collaboration tools you can use to help your team manage complex projects.

Webvizio

Webvizio, a new player in the market, transforms online communication and collaboration into a visual experience using visual collaboration tools. It is part of a single integrated workspace, and it's one of the best tools for sharing visual feedback, managing web design projects that are going on, finding bugs and fixing them, and iterating on designs without any hassle.

Developers and designers can use this tool to sync their intentions, improve user interfaces and designs, and ensure a smooth transition from design to development.

This tool grants webmasters and designers a broad range of collaborative tools. This is the right tool, especially for teams that seek to optimize their design workflows and improve collaboration, with its visual interface, real-time collaboration tools, and design-specific features.

Pros of Using Webvizio:

• Collaboration with seamless visuals. It enables users to add annotations right on top of visuals and forward on problems, or they can upload screenshots and add comments to web pages to give contextual feedback, improve clarity, and reduce mistakes.

• Managing tasks efficiently. With this tool, users can assign tasks, define deadlines, track productivity, and monitor the project progress effortlessly. This is useful to project managers and web developers for managing the workloads of their teams.

Cons of Using Webvizio:

• Problems with email invitations. There have been some reports of users experiencing difficulties accepting email invitations while using this tool, possibly because the invitations did not arrive in their inboxes. Several clients who are less tech-savvy have reported this issue.

• Viewing multi-page PDFs is inconvenient. Several users have complained about the way that Webvizio displays multi-page PDFs. Reviewers have criticized the lack of a scrollable side-by-side page layout, which appears as a separate tab instead of a side-by-side layout.

Webvizio dashboard screenshot Source

Monday.com

Monday.com is an online tool for managing web development projects that is equipped with several in-house features and is compatible with the best collaboration tools on the market.

In addition to offering a collaborative web development tool, it also offers the following features:

• Sharing documents
• Editing in collaboration
• Integration of collaboration tools
• Multiple views
• Projects and dashboards that are customizable

Here, web developers have access to files that can be shared and co-authored in real time using Workdocs. Thanks to seamless third-party integrations, you can continue to use popular collaboration tools like Slack, Microsoft Teams, Dropbox, and so on with Monday.com.

Monday.com also offers multiple views for project management, such as a calendar, timeline, Gantt chart, Kanban board, and more, as well as customizable dashboards and time-tracking features.

Pros of Monday.com:

• Simple Automation. Simple tasks can be automated using rules
• 200 templates Available. There are more than 200 templates available for projects that users can choose from.
• Easy to Understand UX/UI. User interface that is modern and minimalistic which makes it easy to understand for everyone.
• Free Plan. For solo and duo users, a free plan is available

Cons of Monday.com:

• Filtering tool is restrictive: Filtering tools can be a bit restrictive when it comes to tasks
• My Work section is useless. There is little use for the "My Work" section
• No time tracking in the free plan. Time tracking is only available in the Pro plan, which is a major disadvantage
• Mobile App is not very useful. There is a lack of functionality in the mobile app

Source Monday.com dashboard

GitLab

GitLab's main goal is to allow software developers to work together in a collaborative setting while working on code. You can use this project management platform for complete software life cycle development. It's also good at complimenting the DevOps process, where teams work together and complete projects as fast as they can.

Whether you are planning or shipping the code, GitLab has many sets of features. You can monitor tasks, write and run code, perform and report on code quality, track issues, and more. Despite all the complexity of the features, developers are still able to communicate with each other, provide comments, manage pull requests, and merge code in real time.

You can sign up for a GitLab account and choose from one of three tiers: free, pro, and ultimate. However, its price is usually higher than that of its main competitor (GitHub), which may be a disadvantage for some users.

Pros of GitLab:

• An all-encompassing platform. With GitLab, you can manage version control, issues, continuous integration, and more.
• Open-source. GitHub is an open-source platform that makes it possible for users to interact with and modify the source code.
• Ability to collaborate effectively. With GitLab, teams can collaborate easily, with code reviews, merge requests, and real-time comments.

Cons of GitLab:

• It's a steep learning curve. For beginners, GitLab can be a complex tool, requiring time and effort to learn.
• Integrations with third parties are limited. Compared to some other platforms, GitLab may have fewer integrations with popular tools.
• Issues with performance. Performance issues have occasionally been reported by some users, especially for large databases.

_Operations dashboard screenshot Source_

Jira

Jira is a popular software tool that many developers use while working with Agile methodologies. It offers Kanban and Scrum boards, which help team members visualize what tasks must be done, what is in progress, and what is completed.

It also offers roadmaps, which help projects stay on track thanks to their transparency and ease of working together. This tool empowers managers to make team reports that visualize the data and let the them decide where improvements need to be made.

Equipped with more than 3,000 applications, Jira offers seamless collaboration. This tool is free for up to ten users, but for any extra users you'll need to pay. A subscription to the Standard plan costs $8.15, a Premium plan costs $16, and an Enterprise plan costs $24 per month.

Jira is an ideal tool if you are an Agile team that uses Scrum or Kanban methods. It is a program that can help you to run your processes smoothly and efficiently.

Pros of Jira:

• Customization. Teams can customize workflows, fields, and issue types with Jira's powerful customization features.
• A visual representation of work. Jira's intuitive layout and clear status indicators allow users to visualize work items effectively.
• Limit the amount of work in progress. Make sure thresholds are set for work items at specific stages in order to prevent bottlenecks and keep tasks flowing smoothly.

Cons of Jira

• The setup is challenging. A new user of project management tools may find Jira's extensive features and customization options difficult to understand at first, as it has a variety of features and customization options.
• There is no feature for managing ideas. There is no built-in functionality for idea management in Jira, which may force teams to look for other tools to develop ideas and concepts.
• It is expensive for small teams. A small company or startup with a limited budget may find Jira's pricing structure prohibitive.
• The query load time is slow. There have been reports from users that query loading times are slow, affecting efficiency as well as performance, particularly for larger organizations.

Source‌‌ Screenshot of Jira dashboard

Wrike

Wrike's multiple views, time tracking, and other features have helped it become a top player in project management software. It has the capability of file sharing, proofs, approvals, and proofing.

Team members can edit documents in real-time using a live editor while developers attach files to tasks, projects, and folders on the web. Automatic posts are made in real-time to keep everyone updated.

One of Wrike's primary strengths is collaboration with versatility:

• Flexible integrations of other apps
• Multiple project dashboards on one
• Different styles of status views

Web developers can collaborate via various channels within the Wrike platform, including Zoom, Slack, and third-party integrations. It also comes with a couple of project management features, including task tracking and automation, real-time monitoring, and more.

For web development project managers who are always looking for multiple ways of visualizing progress, this tool is appealing thanks to its numerous views.

Pros of Wrike:

• Increased visibility. Team leaders can use Wrike's reporting tools to understand team members' workloads and the status of projects.
• Templates for flexible projects. It is easier to save time by customizing templates for similar projects rather than starting from scratch every time.
• Task management made easy. Wrike is designed to simplify the process of assigning tasks to team members and involving external partners.

Cons of Wrike:

• There is no note-taking tool available. An easy-to-use note-taking tool is desired by users who wish to record notes and then access them at any time.
• Costly for solo users. A free plan is available on Wrike, but it only provides a limited range of features. For individuals or small teams, premium plans offer more valuable features.
• Some integrations delay notifications. Integration with apps such as Outlook may cause notifications to be delayed by more than an hour. If users fail to monitor their inboxes and Wrike, critical messages may be missed.

Source Screenshot of Wrike dashboard

Hibox

The Hibox ecosystem is a comprehensive suite of apps designed to simplify online collaboration and improve productivity. The tool's customer interface is intuitive and offers a robust feature set that can meet the needs of a variety of business types, from online retailers to sales teams to project managers to web developers.

Hibox offeres a range of features to help web developers collaborate, including managing tasks, sharing files, scheduling sprints, collaborating effectively, and tracking progress.

Pros of Hibox

• Easy to use and intuitive. Its intuitive nature is consistently praised by users, with many reporting that their team members were able to figure out how to use it without assistance. It was more efficient to communicate via chat and create tasks rather than email, which resulted in 90% fewer emails.
• Tracking projects effectively. With Hibox's project tracking feature, users are able to stay organized and see how their projects progressed. They can generate individual reports to evaluate their team's performance.
• Collaboration made it easier. With its chat feature and ability to assign tasks, Hibox makes it easy to collaborate among users.

Cons of Hibox:

• Integration is difficult. It has been reported by many users that Hibox has difficulty integrating with the various tools they use in their industries. Some reviewers have found this frustrating and found it hindered their workflow efficiency.
• Not easy to understand for new users. There have been reports of some users experiencing a steep learning curve when they first started using this tool. The platform's initial challenges can make it difficult for users to grasp all of its features and get started.
• Synchronization delays. Many users have reported delays in file synchronization while using it. These delays can slow down workflows and interfere with collaboration.

Source Screenshot of Hibox task dashboard

Conceptboard

Conceptboard is a web-based platform that was developed to enable hybrid and distributed teams to work more efficiently. This digital space allows team members to collect inspiration, generate ideas, collaborate, and create visual content.

This powerful tool allows design teams to work in the same room and turn their ideas into actions using features like wireframing, prototyping, and design review.

Pros of Conceptboard:

• An excellent whiteboarding feature. The whiteboarding feature has turned out to be an extremely useful tool for users. It's a facilitator of brainstorming sessions, and allows users to use the tool as a virtual whiteboard.
• Free templates. The templates of the tool were also highly praised, with users indicating that they were easy to use and of good quality. Templates have also been experienced to be draggable and droppable to the projects, attributed to the speed of project management.
• A valuable tool in the design team's arsenal. Conceptboard helps design teams with activities like user mapping and workflows in the UI/UX design. For designers who work in different fields, this functionality has proved to be of great value.

Cons of Conceptboard:

• Lack of integration capabilities. Some users have gotten into trouble integrating this tool with popular developer software like Jira.
• There aren't any apps developed for mobile phones. Other users have faced challenges when using it away from their computers since there is not a mobile app. As such, they can't use the platform conveniently or any time they like without being tied to their desktops.
• Changing browser windows causes a loading delay. Delays due to changing browser windows have been quite irritating to the users. Consequently, these delays hinder the flow of the work and make switching between tasks harder.

Source Concepboard dashboard sample screenshot

Summary of the Collaboration Tools

Team collaboration is one of the most important components of web development. Each developer tool listed above encourages team collaboration.

To ensure you pick the right software for your team, compare their features, advantages, disadvantages, and pricing.

These collaborative inventions bring together people with different skill sets including developers, designers, and tech enthusiasts in general with one goal in mind to build: to improve and share software freely.

The open source movement champions the idea that knowledge should be accessible to all, and fosters a culture of openness, transparency, and cooperation.

Contributing to open source has many benefits not only for those taking part in it but also the community at large.

Now, if you are just a beginner trying to get into the open-source world, you should keep in mind that you are embarking on a journey that will not only improve your technical skills but also open many doors for you and give you multiple opportunities to interact with like-minded individuals.

This is just a portion of what you can achieve. You'll also have an opportunity to:

• Create an impact through your work

• Build your portfolio

• Network and connect with other devs, and

• Give back to the developer community.

This beginner friendly handbook is crafted to be your companion as you begin your journey into the world of open-source. It will cover concepts that will allow a beginner like you to make your mark in the open-source world.

We will start with the fundamentals of open source, and I'll guide you through setting up your development environment, navigating open-source communities, selecting the right projects, and making your first contribution.

Table of Contents

• What is Open-Source Software?

  • Characteristics of Open-Source Software

  • Types of Open-Source Licenses

• Benefits of Contributing to Open-Source Projects

• How to Get Started with Open-Source Contributions

• How to Navigate Open-Source Communities

  • Understanding community dynamics

  • How to Find and Join Open-Source Communities

  • Etiquette, Communication Norms, and Best Practices

• How to Set Up a Development Environment

  • How to Install the Necessary Tools

  • Text Editors and Integrated Development Environments (IDEs)

  • Version control systems

  • How to fork, clone, and set up projects

• Understanding Project Structure and Workflow

• How to Make Your First Contribution

  • Step-by-Step Guide to Making a Contribution

• Collaboration within the Community

• Beyond Code: Non-Coding Contributions

• Best Practices for Quality Contributions

• How to Handle Challenges

• How to Showcase Your Open-Source Contributions

• Conclusion

• Additional Resources

By the end of this guide you will be equipped with the necessary skills to become an active member of the open-source community. This is the beginning of your open source journey where you will get to continuously learn, collaborate with others, and create an impact. Let's get started!

What is Open-Source Software?

In simple words, open source can be described as source code and projects that are made available to the public to view, use, modify, and distribute under a permissive license.

Open-source projects are usually developed in a collaborative manner, mostly by a community of volunteers. Unlike proprietary software, which is usually controlled by a single entity, open source promotes transparency, collaboration, and innovation through community support.

Open-source projects don't only empower their users to use the projects themselves, but also gives them an opportunity to understand how the project works, contribute to its growth, and improve it too.

The main idea behind the open-source software is not only to share the code but create communities with a culture of collaboration, transparency and shared learning.

With this approach in mind, the open-source world has given a rise to some of the most innovative and impactful technologies in use today.

Characteristics of Open-Source Software

• Free to use - users can feely use, modify and redistribute the software.

• Transparent - source code is accessible to all. This promotes trust among the users, as well as openness amongst developers who peer review and fix bugs.

• Collaborative - most open source projects promote collaboration, which enables different people from around the world to contribute their skills, ideas, and expertise.

• Community-driven - open-source projects foster and promote the building of strong communities of like minded individuals with common goals.

• Diversity - brings together people from different backgrounds who share a common goal.

• Continuous Improvement - open source software is continuously evolving. This means that bugs are fixed regularly, new features are added often, and updates are released from time to time.

• Licensing - each open source software has a license that protects the rights of both authors and users, enabling the software's continued openness.

Types of Open-Source Licenses

Open-source licenses protect the rights of both the authors and the users. They also define terms under which the software can be used, modified, and distributed.

Some of the most common licenses are:

• GNU General Public License (GPL) - this guarantees the end user the freedom to run, study, share and modify the software.

• MIT License - originates from the Massachusetts Institute of Technology (MIT). It permits reuse of proprietary software.

• Apache License- commonly used for projects associated with the Apache software Foundation.

• BSD Licenses - they are a family of free software licenses that impose minimal restrictions on the use and distribution of covered software.

• Mozilla Public License (MPL) - this is a copyleft license that will require the authors to share modifications they make on your code.

• Creative Commons Licenses - most commonly used not only in software but for other creative works, too. Used when an author wants to give other people right to share, use, and build upon their work.

Having an understanding of these licenses at an early stage is really important as they dictate how your contributions can be used and distributed.

Benefits of Contributing to Open-Source Projects

Contributing to open source can be a rewarding way to learn, teach, share, and build experience. There are plenty of benefits that extend beyond the contributions you make.

By contributing to open-source projects you can:

• Learn and Grow - It will open different avenues for you by giving you an opportunity to experience real world development practices, code review processes, problem solving techniques, and so on.

• Build a Portfolio - Your contributions serve as a proof of your skills, which can be helpful when applying for jobs.

• Community and Networking - It gives you the opportunity to engage and interact with like-minded individuals from around the world. It opens doors for mentors and professional contacts who can guide you.

• Solving Real Problems - Some projects are targeted at solving problems faced by many people like security and healthcare. Contributing to them means you are making a direct impact in solving issues that matter.

• Improving Software - The contributions you make may help improve the quality, functionality, and usability of software you use or that's used by millions of people. Each contribution you make, whether it's fixing a bug, typo, or adding code potentially benefits countless users.

• Recognition and Respect - As you work your way into the open-source world and become consistent, you will gain recognition and be celebrated for your work.

• Additionally, it's a fun experience and gives you personal satisfaction. And hey, you never know who is watching, maybe it's your next employer or partner 🙂.

How to Get Started with Open-Source Contributions

Before taking a deep dive into the open-source world, it's important to first evaluate your skills and interests.

Reflect on the programming languages you know, your general technical abilities, and your areas of expertise. Identify your strengths and areas where you want to grow.

This self-assessment will help you find projects that align with your skills and passions.

1. Setting Up the Right Mindset

As you may know, contributing to open-source is not only about code – it's more of collaboration that will promote growth, learning and positive community engagement.

Before getting started, having the right mindset will empower you throughout the journey. For that you will need to:

• Understand the value of open-source - the key principle behind the success of open-source projects is collaboration. Each contribution made, no matter how small, adds value. These collective contributions add benefits to the global community.

• Embrace the learning process - not knowing everything is okay, and that's why open-source encourages learning through collaboration. Remember to always do your research and then, if needed, seek help when you are stuck. This is a sign of progress and not weakness.

• There is more than code - as much as code is the core of most open-source projects, it's not the only way to get involved. Before making contributions consider your strengths and interests and then explore non-coding avenues, too.

2. Choosing a Programming Language/Technology

In order for you to make effective contributions, you'll need to decide which programming languages/technologies you feel most comfortable with. And for that you will need to do the following:

• Assess your skillset - assessing your skillset will help you decide whether to leverage the skills you already have or venture into learning new ones.

• Research technologies - consider technologies used in different projects that you are interested in and whether they align with your interests.

• Personal interests - passion fuels contributions, and contributing to projects that resonate with you can be fulfilling and fun.

3. Finding Projects

Identifying the right open-source projects can really enhance your contribution experience. There are a few different ways you can search for projects. Here are a few highlights on that:

• Use Open-Source Directories - explore different platforms that list different open-source projects. Websites like GitHub Explore, GitLab Explore, Open Source Friday and others all list projects, making it easier to search through.

• Source code platforms - platforms such as GitHub and GitLab are central to the open-source world. Search on these platforms using keywords, and filter across different projects to easily find ones that match your interests.

• Project activity - while searching, look for recent commits, open issues, and ongoing discussions. An active community is a positive sign for the success of the project.

• Community engagement - before you begin making contributions, engage with the project's community. This can be through joining forums, a mailing list, or chat channels. Ask questions and interact with others, as this will help you understand the project's dynamics.

4. Choosing the right project

Ensuring that you pick the right project to work on is important, as it will be the first step to achieving all your goals.

In order to more easily navigate the open-source landscape and find the right project to work on, here are a few thing to consider:

• Interest alignment - Make sure you look for projects that align with your technical interests and areas of expertise.

• Project activity - Be sure to check how active the project is. A project with a vibrant community with recent issues and commits indicates it's actively maintained.

• Friendliness - If you are beginner getting into open source for the first time, opt for projects with a reputation of welcoming newcomers.

• Project goals - Have an understanding of the project goals and be sure they align with your values.

After you have found the project you want to contribute to, it's time to do a little vetting. Make sure it meets the following criteria so you know it'll be a good project to work on:

• Check out if it has a license file.

• Look for the number of contributors.

• Check how often people make commits.

• Does it have any open issues? If yes, this might be a good sign – you will have a place to begin.

• How long does it take for maintainers to respond? You can check and see how often issues are closed and PRs are merged.

• Is there an active discussion on an issue?

• Are the issues getting closed regularly?

• How many open pull requests are there?

• How recently was the latest pull requests merged?

• Do the maintainers thank people for contributing?

If this vetting process checks out, then you are probably good to go and start your contributions.

How to Navigate Open-Source Communities

Open-source projects are more than just code repositories. They are communities where developers from around the world collaborate to create something impactful.

In order to contribute effectively, it's essential to understand the dynamics of these communities and engage with them in a meaningful way.

When it comes to building strong, sustainable open-source contributor communities, it's not just about providing robust newcomer support. For many people, getting involved with open-source projects can be intimidating, overwhelming, and frustrating - especially if they lack exposure to and experience with the different tools and workflows commonly used in the open-source world.

But with the right support structures in place, new members can quickly become valuable contributors to any project - bringing fresh perspectives, enthusiasm, and a willingness to learn.

The benefits offered by these communities are 'on another level' as I would say. They have helped people start from scratch and gain new skills, create connections, and even land their dream jobs.

Other benefits include:

• They promote exchange of ideas, solutions, and best practices.

• Overcoming challenges is often easier as a community, and can make problem solving more efficient.

• Peer review from different contributors ensures code quality, and can help you catch bugs and improve the project in general.

• Contributing to open source projects often provides you with networking opportunities.

Understanding community dynamics

Each open source community has its own culture and values. Understanding these dynamics is key to integrating successfully into the project's workflow.

• Project Vision and Goals - In order for you to make an effective and meaningful contribution, make sure you understand the project's vision and objectives.

• Community Norms and Values - Every community has both written and unwritten rules and values that contributors should respect. These can include coding standards, communication etiquette, and diversity and inclusion principles.

• Recognizing Hierarchy and Roles - Open source projects often have a hierarchy of roles, from maintainers to newcomers. Understand these roles and how decisions are made within the community.

How to Find and Join Open-Source Communities

Finding the right community is an important step to ensure you have a meaningful open-source experience. So here are a few tips you can use to discover and join open-source communities.

• Research - use the readily available platforms to search for projects that align with your skillset. As a beginner at first it might not be a walk in the park for you but with enough guidance you will find it easy.

For starters, platforms such as GitHub, Gitlab and Bitbucket can be good platforms to search for projects. One similarity that cuts across all this platforms is that you can use the search functionality to find projects by keywords, technologies used or specific topics.

For example, using GitHub if you are interested in finding Python development projects they you can have your search as shown below and additionally from the left panel further filter the search to suit your desires.

• Forums and mailing lists - many projects use different ways to communicate. By finding the right one you can easily introduce yourself and ask questions. The communications options you choose will also depend with the kind of info you want to get.

If you are interested in just receiving updates and news about a specific project you are interested in, then consider joining the mailing lists which in most cases is weekly, monthly or quarterly. To sign up for a mailing list/newsletter, you can visit either the official site of the project or a related repository.

If you are more into engaging with other contributors, then joining the forum/discussion boards is the right thing to do. These boards enable the maintainers and contributors to have discussions and share knowledge among themselves. Below is section of freeCodeCamp's forum and some of the conversation that take place.

Note the freeCodeCamp forum is subdivided into different sub-forums. This is a very common practice for big projects as it makes it easier for different contributors with questions to know where to ask for help

• Social Media - follow open-source project accounts on platforms such as X (Twitter), LinkedIn, and GitHub to easily get updates. This works best for those who are actively participating on the social media platforms. For quick updates and news regarding a specific project, then this is the right place to get it – plus it also allows you to enage with other people interested with the same project as you.

• Meetups and conferences - start attending local meetups, conferences, and workshops that are related to open-source projects. This may act as a good opportunity to start making connections.

• Online communities - use platforms such as Stack Overflow, Reddit, and Discord to connect with fellow contributors.

Etiquette, Communication Norms, and Best Practices

Once you've found a community to join, it's important to follow etiquette and communication norms. Here's a guide to best practices:

• Read the guidelines - Read and understand the community guidelines. They help ensure that everyone feels equal, safe, and respected.

• Introduce yourself - How we introduce ourselves will often be how others remember us. When you introduce yourself, remember to be respectful and concise.

• Listen and learn - Before you begin making any kind of contributions, take some time to first understand the culture of the community.

• Ask questions - whenever you encounter a challenge, feel free to ask a question and be sure to provide some context to indicate you did attempt to find an answer yourself.

• Accept feedback - whenever you receive feedback of any kind, thank the person and accept their opinion. Remember that continuous learning is key.

• Don't spam - Avoid spamming the communication channels with the same questions. Just use appropriate channels for different topics.

• Be patient - remember that the communities have contributors from different time zones, so give them adequate time to respond.

How to Set Up a Development Environment

A well-configured environment is the foundation not only for open-source contribution but for development in general.

It may sound like a difficult thing to do, but when you are contributing to multiple projects and working on personal projects from your machine, having an environment will be really helpful.

Here are a few things to note when it comes to setting up your development environment:

Install the Necessary Tools

• Local setup - In most projects, they will list all the requirements needed for setup. Just be sure to install them as instructed on the project's documentation.

• Consider using a virtual environment, as this will help in isolating project-specific dependencies.

• Using Docker is a good option, too, as it ensures consistent environments across different machines you might be working with.

Text Editors and Integrated Development Environments (IDEs)

Text Editors and IDEs are the tools that help your write, edit, and manage your code. Depending on your programming language of choice and personal preference, you can choose from different options such as Visual Studio Code, Sublime Text, or JetBrains IDEs like PyCharm or IntelliJ IDEA.

These tools offer features like:

• syntax highlighting,

• auto-completion

• debugging

These features can help enhance your coding experience.

In addition to the regular installation, be sure to install any necessary extensions that will help make your workflow smoother.

Version control systems

Version control is the cornerstone of collaboration in software development. The most commonly known and used one is Git. It allows you as a developer to record changes made to code, create branches to easily add new features without interfering with main code, and allows easy merging of the changes.

But Git by itself can't accomplish all this, so it works together with GitHub.

GitHub is a web-based platform that allows you to host source code in what is referred to as a repository. Together with Git, GitHub offers multiple beneficial features to developers – but the most important one, apart from collaboration, is that it offers a visual interface for managing the repositories. This makes it easier to track issues, merge changes and so on.

You can learn more about the basics of Git and GitHub in this guide.

Moving forward, just like with any other software, to get started using Git you'll first need to download and set it up. But first make sure that you already have a GitHub account created. If not, you can visit github.com and create one, then proceed with the steps below afterwards.

• Step 1: Download Git from the official site.

• Step 2: Run the executable file to install Git locally. If you are on another OS than Windows, be sure to check the specific commands you can use to install Git from the official site.

• Step 3: Configure Git with your details, including your username and email. For that you will need to open the Git terminal and run the commands below:

git config --global user.name "Your name here"
git config --global user.email "your_email@example.com"

For some extra customization, you can run the commands below. The first one will add some color to the output, and the second one will tell Git to use emacs.

git config --global color.ui true
git config --global core.editor emacs

Now you should be ready to use Git. If you want to learn more and dive in deeper, here's a helpful beginner-friendly Git resource for you.

We will be discussing the most common Git commands later on in the upcoming sections.

How to fork, clone, and set up projects

Now we'll cover some of the most important parts of using Git.

First, what is forking? Well, it allows you to make a personal copy of a project's repository to your GitHub account. This step is important mostly when you want to make contribution to a project that you don't have direct access to.

In order to fork a repo, on the GitHub repository page, click Fork, usually on the top right corner.

This will create a copy of the repository under your account, changing the URL of the project to:

https://github.com/<your-user-name>/projectname

Cloning allows you to download a copy of the already forked repo to your own local machine. In order for you to perform this step, you must have Git installed locally in your machine. If you haven't done this yet, check out the Version control systems section above.

First, you will need to navigate to your account and locate the forked repo. Then copy the URL directly from the browser or click the Code button to copy the URL. You'll have three option to choose from: HTTPS, SSH, and GitHub CLI. You can choose either of the first two options.

Next, in your local machine, open the terminal and run this command:

git clone https://github.com/<your-user-name>/<projectname>

Be sure to navigate to where you need the project to be copied to, for example Downloads, Desktop, and so on:

Alternatively, you can opt to use the GitHub Desktop application to perform all the above steps. But first you will need to have it installed and fully configured.

Next, instead of copying the URL and pasting it on your terminal, select the option that says Open with GitHub Desktop.

Now you'll need to know how to set up the project locally. Navigate to the project directory using the terminal and be sure to install dependencies if there are any that are listed.

To check if everything is set up correctly, run the project locally and ensure that it works as expected.

Understanding Project Structure and Workflow

Open-source projects come in various shapes and sizes, but what's common among them all is the structure and workflow. By having a clear understanding of the development process, it will make your contributing process easier.

Overview of a Typical Open-Source Project Structure

A typical open-source project will have the following people associated with it:

• Author - Also referred to as Owner. Represents the person who created the project. They have the power to assign new roles to other members to help with the project's maintenance.

• Maintainers - They are responsible for driving the vision and goals of the project. They're usually responsible for the direction of the project and are committed to improving it.

• Contributors - This represents people like you who add/make changes to the project in one way or another. They follow the same code review process, are subject to the same requirements on code style, and so on.

• Community Members/Users - These valuable members of the community can provide feedback about features, bug reports, and more.

In addition the different roles and people, the structure will usually look like this:

• The Root Directory will consist of important project files, such as the README, license information, and configuration files.

• The Source Code Directory houses the main source code of the project. It can be organized by either libraries, modules or components.

• The Documentation Directory contains user manuals, guides for any APIs to help users and contributors understand the project.

• The Configuration Files contain files with instructions on how to setup the project's build process, dependencies and other helpful configurations.

• The Assets Directory contains no-code files like images and other templates used by the project.

• The Scripts Directory contains automation tools that the project might need.

Below is a section of the freeCodeCamp repository workflow with most of the files listed above:

How to Make Your First Contribution

Before making your first contribution, make sure that you have chosen beginner friendly issues or task to work on. To help you find good beginner friendly issues/tasks, here are a few tips:

• Browse through project issues trackers on platforms such as GitHub. During the search, look for projects labeled "beginner-friendly," "good first issue," or "help wanted." This are usually designed for beginners. Here's a guide that shares more info on this topic.

• Make sure you understand the issue's description before you begin working on the task. This will help you choose a task that aligns with your skills and interests.

• If you are completely new with no prior knowledge, check for projects that offer mentorships to beginners.

For a detailed guide on how to search for issues and repos on GitHub, check out this guide.

Step-by-Step Guide to Making a Contribution

Now that you know how to search for a beginner friendly project – and assuming you have already gotten one that aligns with your skills – the next step is making your contributions.

For a demo, I will be making a non-code contribution (and I'll discuss more about this later).

• Step 1: Fork the repository

• Step 2: Clone the repo onto your local machine.

• Step 3: Create a new branch

To create a branch, run the below command and remember to give your branch a descriptive name:

git checkout -b descriptive name

This will create the branch and switch to it automatically.

• Step 4: Make the necessary changes – this can be fixing typos, fixing a bug, and so on – it all depends with the issue you have chosen.

• Step 5: After making your changes, it's time to add the new changes into the main branch. You can see all changes made by running: git status

You can choose to add each file modified individually using git add file-name or you can add the modified files all at once using: git add *

You will notice that the changes are no longer highlighted in red but instead in green. This means that they are ready to be committed.

To make a commit, we move on to the next step which is adding a commit message. This basically explains the changes we have made: git commit -m "<message here>".

• Step 6: We need to regularly sync the forked repo with the original repo. This incorporates all the changes made by other contributors. To do this, run the commands below one after the other:

git fetch upstream
git rebase upstream/main

• Step 7: Push the changes to GitHub Now that everything is set, it's time to let our maintainer know what we have added. You do this by pushing the changes with this command: git push origin descriptive-branch-name.

• Step 8: This is the last step, where we submit a PR. For this step you will need to go back to GitHub under the repo you had forked earlier. You should be able to see a pop-up with a button saying Compare & pull request – click on it.

Clicking this will allow you to give your PR a name, add a description of what you have done, mark the checklist (if there is one) to ensure that you have fulfilled all the requirements, and then finally clicking on the Create pull request button which is slightly below the description box.

Then the maintainer will merge all your changes into the master branch of this project (unless they need you to make updates first). You will get a notification email once the changes have been merged.

Collaboration Within the Community

Being part of a new community or environment in any kind of setting isn’t easy – and more so for people who refer to themselves as introverts.

When it comes to open-source communities, newcomers often face various challenges that can deter them from feeling comfortable and affect their contributions.

The first step in fixing a problem is to identify it. This will bring you closer to finding a solution. Some of the most common challenges faced by newcomers in OS communities include:

• Feeling overwhelmed/intimidated by the expertise of other community members.

• Struggling to understand the project structure and codebase.

• Lack of clear understanding of the contribution guidelines.

• Encountering an unwelcoming community.

• Lack of recognition and appreciation of contributions.

• Struggling to find tasks that matches your skills/expertise

By addressing the above challenges, we will be one step closer to creating supportive communities which are comfortable for all. As we know collaboration is key for the success of any open-source project and community engagement can play a major role on your career while at the same time shaping you to become a better contributor.

There are different ways to address these common challenges while at the same time engaging with the community to ensure the project's success:

1. Participating in discussions and forums

2. Giving and receiving feedback on contributions

3. Learning from the experienced contributors

4. Mentoring other contributors and taking part in pair programming.

5. Attending and being part of community events.

In addition to this remember to be patient, stay humble, listen actively, celebrate others, and take part in discussions about the future of the project.

Beyond Code: Non-Coding Contributions

The good thing about opens-source projects is that they can often accommodate people with all kinds of skillsets. Contributing extends beyond just writing code. Non-coding skills are also important to the success of the open-source projects.

If you are looking for different ways to get involved in open-source and don't have coding skills, this section is for you.

Update the Documentation

Good documentation is the backbone of any successful project, not only in open-source but even in the real-world products. Clear and detailed documentation will help users and developers understand the project easily.

Some ways you can contribute to the documentation include:

• Writing tutorials - You can opt to write step-by-step tutorials that will guide users through steps such as installation, setup, usage and troubleshooting.

• API Documentation - Document the project's APIs, and provide code examples for the developers who might want to integrate the project.

• User guides - Write user-friendly guides that break down the complex concepts in simple and easy to understand sections.

Contribute to the Design and User Experience (UX)

Any project that is made for an end user will greatly benefit from a well-designed user interface. If you have some skills in the design field, you can contribute by:

• Improving UI/UX - improve the project's look by suggesting more user-friendly designs and creating mockups for the same.

• Creating Icons and Graphics - design logos, icons, banners and other visual assets that will help promote the project's branding.

• User Testing - take part in testing the designs and provide feedback.

Help with Translation and Localization

Many projects are trying to reach a global audience, and as a native speaker of your language you can help with this.

Contribution by translation and localization ensures that the projects can easily be accessible by people from different backgrounds all around the world. As a contributor you can help by:

• Translating Content - you can translate the documentation, user interface, and any other relevant content.

• Cultural Adaptation - whenever you translate a project, be sure that the content is relevant to the culture and aligns with local contexts.

Participate in Quality Assurance and Testing

It may not seem like much, but testing is crucial for maintaining any good open-source project. The good thing about testing is that even though you are not a developer you can contribute by:

• User Testing - this involves testing the projects under different use cases and giving feedback on any encountered bugs, glitches, and issues. This feedback will help make the project better for the next development face.

• Beta Testing - this involves being part of testing products before they are officially released. Help identify any issues that the end user might encounter.

Engage with the Community

Having a strong community creates a safe space where contributors can focus on major things like improving the software's quality and ensuring the long-term sustainability of the project. You can contribute by:

• Moderation - you can offer to moderate discussion forums, chat rooms, and community platforms to ensure a positive and inclusive environment.

• Answering Questions - you can assist other community members by answering any questions that they may have.

Do Marketing and Outreach

The more an open source project is visible to the community, the better - and this includes visibility on social platforms. If you have marketing or communication skills you can contribute by:

• Promoting the projects on social media platforms.

• Writing tutorials and articles that highlight features offered by different projects, along with their importances and use cases.

Help with Fundraising and Donations

Lack of adequate funds to support the project's growth and sustainability may lead to its collapse before you even know it. A good way to address such a problem is by:

• Fundraising initiatives - organizing fundraising campaigns to support the project financially.

• Sponsorship outreach - applying for grants, seeking sponsorship, and joining incubator programs.

Best Practices for Quality Contributions

Contributing to open-source is not just about writing code, it's about creating high-quality and valuable contributions that will make the project easily accessible to others.

Here are some best practices that will help you contribute code that is clean, easy to maintain, and follows the industry standards.

Write Clean and Maintainable Code

Clean code can be described as code that is easy to read, understand, and maintain.

By writing clean code you will not only make it easier for others to read through but also for your future self.

When trying to write clean code, here are some key best practices:

• Use meaningful variable, function, and class names.

• Break down the code into smaller managable sections.

• Make use of comments to provide additional context.

• Maintain consistency in your coding style.

• Don't Repeat Yourself (DRY)

Test and Document Your Code

• Always write unit tests, integration tests, and end-to-end tests to ensure that the code works correctly.

• Remember to always document your development progress. This includes the code's purpose, usage instruction, and so on.

How to Handle Challenges

Being a new person in any field, you are bound to encounter different challenges that may make you question your desire to contribute.

But you can also see the challenges as stepping stones rather than roadblocks, preparing you to be a better contributor.

How to handle rejection and criticism

Rejection and criticism can be tough to handle, especially for beginners. Not everyone in a community can be as welcoming as we'd like, but just remember – this experience is still an opportunity of focus and improvement.

In case you encounter rejection and criticism, here are a few things to help you overcome them:

• Maintain a growth mindset - approach the rejection with an open mind and view it as a chance for you to learn and improve on your skills.

• Ask for feedback - in a case you have made a contribution and it has been rejected, always ask for feedback. This will help guide your future contributions while at the same time improving your skills

• Learn from others - before making your contributions, take time to learn from what other experienced contributors are doing. This can help you know how to structure your code, write documentation, and how to address issues. In return you will be on the safe side while making your contributions.

• Be persistent - use rejection as a motivation to refine your work and resubmit again.

How to ask for help

Many beginners, not only in the open-source world but in other fields as well, may be hesitant to ask for help. This is often because they don't want to appear to be inexperienced.

If you find yourself feeling this way, you may be forgetting that you're new to the field, and asking for assistance is part of the learning process. Even if you're a more seasoned contributor, you may still feel insecure at times (imposter syndrome, anyone?) - and this is ok. Everyone has their doubts at times. Just keep pushing forward.

As a beginner in open-source, to ensure that you receive the help you need, here are some tips:

• Do your research - attempt to solve the issue by yourself first before seeking help. This demonstrates your commitment to learning and problem solving skills.

• Be specific - provide detailed info about the problem you are facing. This can include mentioning the steps you have taken so far, the result you have gotten, highlighting the errors you faced, and so on. The more detailed the question, the easier it is for others to help you.

Strategies for Overcoming Common Challenges

1. Time management - balancing between open-source and personal work can be challenging sometimes. Be sure to set realistic goals and avoid overcommitting.

2. Impostor syndrome - this is where you feel inadequate despite there being solid evidence of your skills. Remember that we all begin somewhere – just try to appreciate your learning journey and focus on your progress.

3. Large code bases can be overwhelming to beginners. As a good practice, start small and work your way up as you gain more confidence and familiarize yourself with the codebase.

4. Burnout prevention - prioritize self-care, take breaks when necessary, and always remember that making small steps is more valuable than overwhelming yourself with a task.

How to Showcase Your Open-Source Contributions

Just like in any other field of work, you need to market yourself. And one of the best ways to do that is by showcasing your projects and contributions online. It's time to shine a spotlight on your work.

In return, this may attract potential employers, collaborators, and give you recognition in the broader tech ecosystem.

Build an online portfolio/profile

The most common way to showcase any form of work online is through personal portfolio and here is how you can achieve this to showcase your open-source contributions:

Begin by selecting a platform that best works for you. This might include GitHub pages, your personal website, and platforms like Behance or Dribbble for designer-related projects.

Now that you have a platform, organize you your work in categories including a brief description, role played, and any challangages you might have encountered.

Remember to add code samples for different projects you have wokred on and a brief explanation of what the project/code does.

Finally, add a short bio that highlights your passion for open source and technology. Make it engaging and relatable.

Highlight your contributions on your résumé/social media platforms

This is mostly helpful when potential employers are reviewing your résumé or GitHub/LinkedIn profile. Your contributions may set you apart from other applicants.

Here is how you can utilize this to stand out:

• Have a dedicated section where you can list all your open-source contributions and a brief description of your involvement.

• Quantify the impact that you contribution played to the success of the project.

• Highlight the skills you gained through contributing to open-source.

• If you have an online profile, be sure to include a link of it on your resume, this will help recruiters explore your contribution in depth.

Networking

Networking can open doors and connect you with multiple opportunities.

Here is how you can leverage your open-source experience for networking purposes:

• Talk about your contributions to open-source projects. This can be through sharing insights, asking questions, and so on.

• Attend meetups and conferences related to technologies you have worked with or have experince in.

• Connect with fellow contributors on platforms such as GitHub.

• Take part in hackathons, workshops, mentorships and collaborative coding events with people os same interest.

• Share your thought by writing tutorials about your open-source experiences, challenges you've overcome, and lessons you've learned.

Conclusion

As you come to the end of this guide, take a moment to reflect on the journey. You have gained valuable insights while at the same time discovering how impactful you contributions can be no matter how small they are.

If you have contributed to open-source before, think back to when you first began your open-source journey. Remember the joy you felt when your first PR was merged, the satisfaction you had when you solved that bug, wrote that line of code, resolved that issue, or updated that documentation.

All this has left a mark on the projects you have worked on. Be proud of yourself 😊.

Remember that the open-source community thrives on diversity, and every contribution, no matter how small, adds value. By participating in open source, you're contributing to a global movement that values transparency, cooperation, and the free exchange of knowledge.

Here's to your continued success in open-source contributions, learning, and making a difference.

Happy coding! 🚀🌍

Additional Resources

• Open Source Projects Every Developer Should Know About

• How to Use GitHub Actions to Automate Open-Source Projects

• GitHub Search Tips – How to Search Issues, Repos, and More Effectively on GitHub

• How to Write a Good README File for Your GitHub Project

• Developer Communities to Join to Help You Grow Your Tech Career

• How to Contribute to Open Source Projects – A Beginner's Guide

When working on a project with multiple collaborators, you must be able to fetch changes from the remote repository and merge them with your local repository. This article will teach you how to fetch remote branches in Git.

What is a Remote Branch?

Before diving into how to fetch remote branches, let's define a remote branch.

A remote branch is a branch that exists on a remote repository, such as GitHub, GitLab, or Bitbucket.

When you clone a repository, Git automatically creates a "remote" that points to the original repository. You can then use this remote to fetch changes made by other collaborators on the project.

How to Fetch Remote Branches in Git

When you clone a repository, you can access all its remote branches. You can verify this using the git branch command alongside the -r option:

git branch -r

You can checkout to any of these branches using the git checkout command.

When you are working with a group of people, one contributor creates a new branch remotely. You may need to fetch this remote branch into your project. You can do this with the git fetch command.

The git fetch command goes out to your remote project and pulls down all the data from that remote project that you don’t have yet. After you do this, you should have references to all the branches from that remote, which you can merge in or inspect at any time.

git fetch

You can attach the remote repository name, which by default is origin:

git fetch origin

It is important to understand that when you use the git fetch command, it only downloads the changes made in the remote repository to your local repository without automatically merging them with your work or modifying what you are currently working on. You will need to merge the changes manually when you are ready.

To access the fetched content, you need to use the git checkout command. This ensures that fetching is a safe way to review commits before integrating them into your local repository.

If you want to fetch remote branches and merge them with your work or modify your current work, you can use the git pull command. To achieve this, use the following command:

git pull --all

You can then run the git branch -r to verify if the remote repository has been added.

Wrapping Up

Fetching remote branches in Git is a crucial aspect of collaboration in a development environment.

By following the steps outlined in this article, you can fetch changes made by other collaborators on remote branches and merge them with your local repository. This enables you to work on different branches of a Git repository and collaborate effectively with other developers.

Embark on a journey of learning! Browse 200+ expert articles on web development. Check out my blog for more captivating content from me.

Have fun coding!

No matter how experienced of a developer you are, being interviewed for a new job is always stressful. This is certainly true from my own experience.

In my case, I have been working professionally as a Software Developer for two and a half years, and I've had to face developer interviews five times already.

I have seen people focus too much on learning specific algorithmic problems, or training in online platforms specialized in interview challenges. But there is another side to interviews which I think is as important – and people pay less attention to it.

So, if you want to know how I think you should focus your training for interviews, grab a cup of coffee and get comfortable.

It's going to be a bit of a ride ride (but don't worry – Python examples included!).

Here's what we'll cover:

1. Do algorithms and data structures matter for interviews?
2. Focus on a collaborative approach
3. Try doing a mock interview
   – The initial example interview problem
   – The second example interview problem
   – The hardest example interview problem
4. Final words

Let's dive in.

Do Algorithms and Data Structures Matter for Interviews?

The short answer is Yes.

Knowing about Data Structures and Algorithms will often help you get a job. Also, the benefits of having a solid algorithmic background include the capacity to make better decisions when faced with a challenging problem.

In real life, algorithmic problems won't appear like the statements in the academic exercises you might study. Still, the more trained you are the most likely you are to be able to recognize an application of a Balanced Binary Tree or a Shortest Path algorithm in disguise.

With this in mind, I would recommend not training Data Structures and Algorithms solely for the interviews that you want to excel at. The design of algorithms and how to use the right data structures are topics beautiful enough to be studied just for the pleasure of knowing.

The scope of an interview is very limited. Instead, focus on the problem-solving part of the issue. Try to understand how to use an algorithm (or variations of it) for similar tasks. Study all the variants, and learn to recognize them in different situations. This will help you face new tasks with an open mind.

Also, don't memorize solutions. It won't take you anywhere. It is very easy for an experienced developer to ask the right questions that will put you on display if you only train for very specific topics.

Take a problem and try to solve it using different methods. Try to solve harder problems every time. Get out of your comfort zone.

It will pay off.

Focus on a Collaborative Approach

Most people train for their interviews on websites like Leetcode. There is no problem with that. These websites are good for training your problem-solving skills.

I have been participating in Competitive Programming contests for the last eight years at least, and I have always benefited from these online resources.

But there is one thing that's hard to understand for most software engineers wanting to perform well in an interview. They don't train for the most important aspect of software development: Collaboration.

Usually, when you are faced with a problem in an online platform, it comes with some constraints on the maximum values for some input. It also might have some time and memory limits that require you to adjust your solutions to be more or less efficient. But this is not how it will be in real life.

It is not obvious how to map these constraints to real-life scenarios. They usually come in the form of very specific requests from a client, or very specific characteristics of the team.

In a real project, the team will collaborate to determine what these constraints will be. You have to analyze your use cases, the time you have for the task, who is the final user, how many people will be working on it, and so on...

After a series of discussions, you will reach a consensus and finally start implementing a solution that suits your needs. And this solution doesn't even have to be the more efficient in some cases, but the fastest to implement, for example.

This is what interviewers want to see from candidates during the interviews as well.

You don't jump straight to implementing the best solution you know for the problem you are facing. Instead, you should use your interviewers as a valuable resource, treat them as if they were your teammates (in the end, you want them to be). Ask questions about how the team prefers the solution for the problem to be implemented.

This will lead to a very fruitful discussion where you can showcase your coding abilities and your collaborative skills. You could start proposing simple solutions and walk your interviewers through the process of how the solution can be improved using the best Aces up your sleeve.

As a final note on online training, I would recommend doing individual and team training. Use websites such as Codeforces or AtCoder, which have a huge set of interesting (and challenging) problems, and try to compete against yourself every day.

Don't focus on your rating. I have done that before, and it only holds you back.

Try Doing a Mock Interview

If you reached this point in the article, I would like to propose a little exercise. Let's have a mock interview where I will act as the interviewer. I will tell you how I think the candidate (you) should answer every question and perform each task.

Of course, we will focus only on the programming challenge part. Other aspects of interviews, such as talking about previous experiences, are also important, but we will try to cover that in another article.

So, if you feel ready enough, let's go!

The Initial Example Interview Problem

Let's start with the task that you will be solving. Keep in mind that if you and I are ever in this situation, I won't be using this same example, but of course, I will be using the same methodology 😉.

The statement of the problem is the following:

"Given an integer number X, find out if it is a prime number."

You might be tempted to go for the best solution you know to solve this problem. I think that this approach, as I explained before, isn't always correct.

Instead, what I would like to know are the different approaches to solving this problem. Also, I would like you to ask about the requirements for this task. Something like:

• Should we aim for performance or to solve it faster?
• Should we make a solution that is easy to understand for other developers?

Usually, some aspects to consider when creating the first solution for a problem are:

• Easy vs Hard: Should we make an easy-to-implement solution even if it is not perfect, or should we go for a more robust solution that will be difficult to implement?
• Naïve vs Efficient: Should we deliver a working, naïve solution first and then a more efficient one, or should we go straight to efficient?

Evaluate what your team wants to optimize for. Reach a consensus, and implement the agreed solution.

In my case, I would be glad if you proposed the easiest, fastest-to-implement, correct solution that you can think of and then guide me through the process of how to improve that solution.

An example of a very good initial solution to this problem is something like the following:

# naive.py

def is_prime(x: int) -> bool:
    if x in [0, 1]:
        return False
    for i in range(2, x):
        if x % i == 0:
            return False
    return True

As you can see, this function is correct. Since a prime number is an integer only divisible by the number 1 and itself, it makes sense to iterate from 2 to x - 1 looking for a divisor of x. If we find one, we can immediately return False. Otherwise, we return True. As edge cases, the numbers 0 and 1 are not prime by definition.

This is a good starting point!

Now, before diving into optimizing this method, you can discuss the style of the code. Is it Pythonic enough? Do we care about it? Is it readable?

All these questions might not seem important at first but, since we work as a team, they do matter. Having a coding style is important because it makes it easier for every team member to understand each other's code, and it will speed up reviews and refactoring. Also, the code is more often read than written, so readability counts!

You might be tempted to show off your Python skills and rewrite the previous function as follows:

# pythonic_naive.py

def is_prime(x: int) -> bool:
    return False if x in {0, 1} else all(x % i != 0 for i in range(2, x))

I think this is a good, pythonic way to write this function. But, since the team is the most important thing here, this change should be discussed.

It might be the case that some team members are not so skilled in Python. Maybe, in this case, we should optimize for readability instead and keep the function as we first wrote it.

A more interesting addition, before getting into performance, would be adding docstrings to the function. As I said before, this code is most likely to be read by your team members in the future. It is important, then, to make it easier for them (and your future self) to understand what this function is doing.

Maybe changing the function to something like the following will add more value:

# naive.py

def is_prime(x: int) -> bool:
    """This function takes an integer `x` as
    argument and checks whether is prime or not.

    Args:
        x (int): The integer number to test for primality.

    Returns:
        bool: True if the number `x` is prime, False otherwise.
    """
    if x in [0, 1]:
        return False
    for i in range(2, x):
        if x % i == 0:
            return False
    return True

First Optimization

Until this point, we have an initial solution that works. We have discussed important topics such as code styling, readability, and documentation for developers. These are all important things to consider when working as a team.

But we still haven't talked about the performance of the solution! So, it's probably time for that.

At this moment, you should probably bring up that this function can be implemented so it runs much faster. And now is when you showcase all that algorithmic knowledge inside you.

The previous solution has a time complexity of O(x), where x is the input integer the function takes as an argument. This can be optimized to O(sqrt(x)) with the following code:

# sqrt.py

import math

def is_prime(x: int) -> bool:
    if x in [0, 1]:
        return False
    for i in range(2, int(math.sqrt(x)) + 1):
        if x % i == 0:
            return False
    return True

Or even like this, without importing the math library:

# sqrt.py

def is_prime(x: int) -> bool:
    if x in [0, 1]:
        return False
    i = 2
    while i**2 <= x:
        if x % i == 0:
            return False
        i += 1
    return True

I would be ok with either alternative.

I omitted the docstrings in the previous implementation for the sake of making the actual code changes clearer. But, it would be great to include the time complexity of the function in the documentation for developers. The more information you can give about your code, the better it will be for your team members and yourself.

You are doing great so far. Let's continue!

The Second Example Interview Problem

So far, I have been able to evaluate that you have the necessary collaborative skills to take on easy tasks with the team. Now it's time to complicate things a little.

This is the statement of the second problem I would propose:

"Given two integer numbers L and R, count how many prime integers are in the interval [L, R]."

Once again, I would recommend discussing what priorities the team has set regarding this task. Start simple and walk through the process of improving an initial solution. Emphasize that premature optimization is not a good practice.

Also, discuss the possibility of using the solution that you implemented for the previous task to solve this one. It makes sense that if we have a function that tells whether an integer is a prime number or not we can use it for every number in a range.

And this is something that you will have to do in real life. Usually, when a new task shows up, the team should look into the maintained projects to see what can be reused to speed up the implementation process. If you don't do this, you might end up coding duplicated functionalities.

That being said, a good initial solution for this task could be something like this:

# range_primes.py

from sqrt import is_prime

def count_primes(l: int, r: int) -> int:
    primes = 0
    for i in range(l, r + 1):
        if is_prime(i):
            primes += 1
    return primes

This is perfectly fine, and you have shown that you can reuse previous functionality to build new ones. As in the first example, you might be tempted to show off your Python skills and write this function like this:

# range_primes.py

from sqrt import is_prime

def count_primes(l: int, r: int) -> int:
    return sum(bool(is_prime(i)) for i in range(l, r + 1))

I recommend not going for this Pythonic implementation as your first option. Leave it for discussion, evaluate the readability of the code, and maybe analyze the differences in performance. Don't forget the docstrings!

The next section is when things get interesting. Keep reading. We are on the final step...

The Hardest Example Interview Problem

Remember when I said previously that the constraints present in competitive programming websites are hard to map to real-life requirements?

Here is how I would present a difficult challenge for you to determine those constraints and implement the best solution that you can:

"Suppose a client wants us to provide the functionality of calculating prime numbers in a range as a service. They want the focus to be on performance because they plan to use this service very often. How would you implement it?"

If you have been practicing your algorithmic skills for interviews, you have probably solved problems similar to this one a few times. The main difference here is the change in context.

Instead of giving you precise instructions, numeric constraints, and input or output formats, I gave you a broader description of the task. And my goal here is the same as before: get you to interact with me as if we were teammates figuring out how to solve this problem from the little information we know.

Hopefully, after exchanging a few questions and answers, we can translate the previous, more ambiguous statement into something much more familiar:

"Given a set of queries of the form [L, R], answer, for each query, how many integer numbers inside that range are prime."

And this makes sense because the client wanted to use this service very often, as stated in the description.

We want to focus on performance. That should be our main concern when implementing the solution. But still, the best way to get to an optimal solution is to start with a simple one, analyze if we meet our performance requirements, and keep improving gradually. Let's see the entire example.

We could start by using the solution we implemented in the previous step. Is it good enough?

Let's assume that the maximum range of numbers we will have as an argument to our function is [1, 10^6]. Also, realistically, let's assume that the number of queries our service will answer per minute is around 10^5.

Our previous solution has a time complexity of O(sqrt(n)) to determine if a number is a prime. If we were to do that for every number in the range, the complexity goes up to O(n * sqrt(n)). On top of that, if we do that for every query, we will end up with an even higher time complexity of O(q * n * sqrt(n)).

Substitute the previous variables with the highest possible values they can have, and you will get that this solution will take around 10^14 operations to answer all the queries. Assuming that a computer can perform around 10^8 elementary operations per second, it will take approximately 10^6 seconds to complete all of them.

Note: Convert 10^6 seconds to days. You will be amazed 🤯.

This solution is unfeasible if the goal is to prioritize the performance of our solution. Let's see how we can improve it.

At this point, what I would expect is for you to take out the best of the training that you've had on all those online platforms, and show me an impressive solution. This is the time to showcase all your analytical and algorithmic skills.

But only now, because I know that you are a team player.

The Final Solution

Since this is a mock interview, I am very interested in knowing your approach to solving this last problem efficiently. Let me know how you would implement the solution or share your code on GitHub – don't be shy.

I guarantee you one thing: if you can make it to this point in real interviews, probably it won't matter too much if you don't know the optimal solution to this problem. It doesn't mean that you shouldn't try your best to solve it, but rest assured that you have done a very good job already.

That's it! Now I want to see your code.

Final Words

In this article, I tried to summarize some of the aspects I consider to be the most important in coding interviews. I placed special emphasis on the collaborative part because I think most people underestimate how important this skill is. It is a must, especially if you want to work on a team with other developers.

I tried to guide you through a mock interview where I explained the thought process I would follow when faced with a standard coding task in an interview. I hope this exercise was useful and that it can help you in your next interview (as a candidate or as an interviewer).

Share your thoughts on this mock interview, and let's start a fruitful discussion.

See you soon! 👋

Sources

• Code examples used in the article can be found here.
• Hint for the last problem: implementation of the Sieve of Eratosthenes algorithm.

👋 Hello, I'm Alberto, Software Developer at doWhile, Competitive Programmer, Teacher, and Fitness Enthusiast.

🧡 If you liked this article, consider sharing it.

🔗 All links | Twitter | LinkedIn

Many people want to be involved in this open side of tech, and luckily there are many different ways to contribute.

Still, open source can be scary at first sight. My first official contribution was during Hacktoberfest 2021, and even after that, it took me while to really feel welcome.

The open source community helped a ton, and it's the route I would advise any new techie to take – get involved with the community around a project you care about.

In addition to being a contributor – making updates to open source code bases, updating documentation, and so on – you can also eventually become a project maintainer. Maintainers are responsible for the thrill you experience when your pull requests get merged.

As daunting as it is to become a first time contributor, it is also quite scary becoming a first time maintainer. So in this article, I'll discuss some of the soft skills project maintainers should cultivate to be successful.

A Little Background

After open sourcing a project very close to my heart, I was lucky enough to gain some much needed experience. I also held a Twitter space with some amazing folks, and they had much to share as well. Hence, this article.

I won't say I am an expert, but to successfully scale an open source project, no matter how big or small, there are certain skills you need to have. And some of these I didn't pick up until after I had been a maintainer for a while.

Skills You Need to Maintain an Open Source Project

Develop Good Time Management Skills

On day one of releasing the project, my email was flooded with GitHub notifications.

I was happy people where checking the project out, but it was too much for me to handle. I was putting off work to attend to issues, assigning, labeling, merging pull requests, fixing conflicts... It quickly became too much to manage. I needed to allocate time and set boundaries.

If you are running a big project, notifications are probably nothing new. If you're running the project alone (like I was at that point), it is way worse.

Putting aside specific time to attend to GitHub tasks was the best way out. It could be in the morning before work, or after work, or only on weekends, depending on what works for you and the project.

Be Patient

I hear people advise contributors that they shouldn't spam maintainers if those maintainers can't attend to their issues/pull requests in time. This level of understanding should go both ways.

Contributors also have lives. If a contributor claims an issue, it is important to give them time to actually submit a pull request. Open source is fun (we've agreed on that already, but just for emphasis), but some people can only contribute in their spare time.

If a claimed issue is taking too long to address, a subtle reminder is fine. Constantly reminding a contributor that they need to submit a pull request could be off-putting, and it isn't a good look for you or your project.

On some rather large projects, however, a time frame is given to contributors who claim issues. I've seen cases where a contributor has about seven days to raise a pull request. While this is understandable because of the fast paced nature of these projects, I personally feel that it's too much pressure, especially for new contributors.

Be Empathetic

For me, this is the most important skill. I can remember my first open source contribution. The joy I felt when my pull request got merged and the immense support from the community were wonderful.

Think of this when you merge pull requests. It could be the contributor's first time too. I try to close off pull requests with a message other than just 'LGTM'. It can be as simple as throwing in a bomb emoji, and thanking them.

People come back to a place where they feel welcome.

Be Firm

This can be hard, but it's also important. You won't merge every pull request that is opened, and that's a fact. But abruptly closing off a pull request without justification isn't exactly good practice either.

If a pull request is too big, or it doesn't add to the project like you would've wanted, it is okay to close it. But do not be afraid to kindly explain to the contributor why it can't be merged. Don't leave a pull request open forever because you feel guilty about closing it.

People can be more understanding than you think if you give them simple common courtesy.

Work on Communication Skills

Collaboration is the basic foundation of open source as a whole. And to collaborate effectively, you need to be a good communicator.

Having people come in and work with you on your project is cool and all – but if you can't properly communicate with these people, you'll end up with a closed open source project (if that makes sense).

Collaboration doesn't have to be you spinning up some huge discord server for the project. It could just be you sharing messages in your code reviews.

If the comment sections under your issues are too small, then GitHub has a discussion tab for each repository. This is a great place to spin up new ideas and start some great connections.

You never know whom you might meet!

Listen and Learn

After open sourcing my app, I've probably learnt more React than I would've if I was watching tutorials and building in private.

Smart people will come along and open your eyes to ideas that you couldn't have thought of on your own. My project has improved so much, mainly because I wasn't afraid to try out new things.

The community wants to help – so let them.

Cultivate a Community Spirit

Someone recently reached out to me, saying they wanted to get involved in reviewing pull requests because it was fun. They aren't officially a maintainer, but I would like to think that they enjoy being a part of the project.

Building an open source project is a community effort. And as a maintainer, you will need that community spirit.

You need to be excited with what you do. Collaboration should be fun. You are happy that the contributor added something, but let them also be happy that they contributed.

People love good, honest feedback. And it also helps you build up your little community.

Be Responsible

If the open source project is your idea, then you're the pioneer. If you decide to be the lead maintainer, be the lead maintainer. Be reliable, and most importantly, be present.

Even if you are a supporting maintainer for some big project, it is good to show that you know what you're doing and that you're committed to the project.

Some projects go stale because the maintainers stop responding to issues and pull requests. It's true that life catches up to us sometimes. If you decide to commit to a project, though, it's important to always show that the project is alive.

But how? Well, everything leads back to collaboration. Keep your collaborators involved and they'll help you out.

Be Nice and Welcoming

People are coming from different backgrounds to check out your project. Whoever they are, they won't come back if their first experience was a mean maintainer, whose project had poor documentation.

No matter how easy you make things, expect questions. Be ready to answer these questions. Point people to the right resources, no matter how obvious the solution could be.

If a contributor is having a hard time, check your documentation. Most times, it's not them, it's us (pun intended). The README might've skipped some steps, or a screenshot wasn't clear enough. Instead of telling them off, point them in the right direction and update your docs if need be.

Conclusion

All in all, being a maintainer is hard work. Whether you're going solo on your project, or working with other maintainers, the goal is the same: collaborating to build great products.

Projects with poorly structured management and responses are one of the main reasons some people feel discouraged when it comes to contributing to open source.

The skills I've covered here are mostly based on personal experience, but I hope they help anyone maintaining a project, or thinking of being an open source maintainer.

If you want to check out my open source project, you can do so here.

In this article, I'll give a high-level explanation of what open source software (OSS) really is, its advantages in the modern technological world, how to use it, and some best practices to follow when using or contributing to an OSS project.

You will learn about widely used tools and techniques like GitHub and continuous integration, as well as what license to choose and how to promote diversity in open source projects.

You will also get to make your first open source contributions if you haven't done so already.

Both maintainers and contributors to open source projects should read this article.

Table of Contents

• What is OSS?
• What is Proprietary Software?
• Open Source Governance Models
• Why Use Open Source Projects (Advantages)?
• How to Work on an OSS Project
• How to Contribute to Open Source Projects
• Helpful Contribution Tips
• Continuous Integration and Delivery
• OSS Licenses and Legal Issues
• How to Choose a License for Your OSS Project
• How to Build Better Open Source Software Projects
• Understand that Leadership is Not Control
• Why Many OSS Projects Fail
• Diversity in OSS
• How to Use GitHub for Hosting OSS Projects

What is OSS?

OSS stands for Open Source Software. This type of software has freely accessible source code under a license that lets you examine, modify, and use that code without restriction.

What is Proprietary Software?

As opposed to OSS, many companies use proprietary software instead. Only the owners of proprietary software have complete access to the source code. Trusted partners can inspect the code once they've signed a non-disclosure agreement.

When using proprietary software, you must agree to a license that limits your ability to share the product.

Open Source Governance Models

Any organization that wants to succeed needs to be organized. It's important to carefully consider how the organization make decisions and who makes them.

Establishing a Governance Model helps determine how you can accomplish this. Let's talk about some of these models now.

Company-led Governance Model

In this model, software development and release management is handled by a single entity.

• External contributions may or may not be requested.
• Plans and release dates may not be publicly disclosed, and unofficial conversations may not be made public.
• Software is in the open (that is, it's public) when it is released.
• An example of this model is Android by Google.

Benevolent Dictatorship Governance Model

In this model, one individual has a dominant influence over the software – hence the term "dictator" (but in a much more positive sense here).

• The quality and effectiveness of the project are greatly influenced by the dictator's intelligence and managerial ability
• As a project matures, the maintainer writes less code, which can cut down on discussions and speed up progress.
• An example of this type of governance is Wikipedia

Board of Governors Governance Model (Tighter Regulation)

• All discussions are public via mailing lists, and collective choices are taken.
• The governing board decides who may contribute and whether new software is accepted.
• Releases are sometimes made less frequently, but they are carefully debugged.
• Examples are Debian and FreeBSD

Why Use Open Source Projects (Advantages)

There are quite a few advantages of going into open source development. Here are some of them:

• You collaborate with other contributors and often get better results
• The source code is often more secure and higher quality
• Using OSS best practices helps developers become better
• It reduces the development cost
• It decreases the time to market
• Customers can trust the quality because there are no secrets and they know what they are getting
• You'll have access to a vast array of inexpensive or free instructional aids for education and learning
• It's a good way to introduce beginners to the workplace

How to Work on an OSS Project

How to Contribute to Open Source Projects

Before contributing to open source projects, you should do some research around the project. Here are some ways to prepare:

Investigate the project

Before you start working on a project, you'll want to learn more about it. First, you should identify and understand the project workflow and styles it uses. Second, you should figure out the scope and nature of the work that needs doing.

Learn About its Communication Methods

Identify how the project maintainers communicate, either through study archives, a mailing list, or some online groups or chat platform.

Figure Out How Contributions Are Submitted

Contributions to the OSS project can be in the form of a mailing list, email, or – perhaps most commonly – through the Git version control system.

Study the Project's Previous History

Studying the history of the project is always a great idea so you know how it started and how it's been developed. Check if the project offers veteran contributors as mentors.

Be the Janitor at First

Offer your services for testing, finding bugs, and so on before you begin to submit code. This is healthy for beginners and people new to the OSS lifestyle. It's meant to be a temporary stage.

Understand the Project's Language

People frequently get interested in learning new programming languages by participating in open source projects that use those languages. But don't use the project as a way to learn the language.

Before thinking about making a software contribution, you should have some familiarity with the language. Most maintainers want qualified contributions only – they likely don't have time to teach you Python or JavaScript, for example.

So make sure you are proficient in the programming language(s) the project uses before contributing. Don't begin learning with a project.

Be Respectful

Being polite and respectful is an integral part in the OSS community as it involves diverse people. Always avoid flaming and trolling, as they have no place in the open source community.

Find a Balance

Try to achieve a balance between asking for feedback and suggestions early in the process and delaying your requests too long and overloading maintainers with a bunch of work at once.

Study and Understand the Project's Structure (DNA)

Most likely, the project already has a formal or informal leadership structure and a community-established culture.

Look into the project's purpose and the impetus behind it. Learn about how big or small the contributions typically are, how vibrant the community is, and what kind of license is being used.

Helpful Contribution Tips

To successfully make contributions to open source projects, there are some best practices you can follow.

First, you'll want to identify the maintainers, their work, and their techniques‌‌. There are projects with a single maintainer or many maintainers for individual subsystems.‌‌

Maintainers have various responsibilities as well. They need to be able to understand and review all submissions and verify that they do not add unnecessary complexity or defects. They should also make sure that these changes don't conflict with existing code.

You can develop a rapport with project maintainers and help them with debugging, reviewing, and other tasks as needed.

It's also important when you're working on a project to get input early and work in the open.

Here are some other quick tips to keep in mind:

1. The project probably has a lot of history, so check to make sure your issue hasn't already been resolved or someone else hasn't submitted a pull request to fix it. Your proposal might be a dated one.
2. Don't propose a fresh idea and have someone else carry it out. This shows that you're not committed to contributing.
3. If you are uncomfortable having other people look at your work often, OSS might not be the best fit for you. However, it could be an opportunity to learn how to take feedback and constructive criticism.
4. Contribute a little bit at a time – don't make a large code dump all at once.
5. Leave your ego at the door. You will sometimes get hash reviews and you need to be able to calmly internalize the feedback.
6. Do not discriminate against others.
7. Be patient and work to develop long-term professional relationships with others in the OSS community.

Continuous Integration and Delivery

When you're working on an OSS project, there will probably be established guidelines for the codebase to prevent conflicts, since many contributors will be working together on it. Testing can also help make sure the code works as it should.

What is Continuous integration?

Continuous integration techniques help ensure that testing is done often and that any issues won't go undiscovered for long. CI also helps make sure that scattered developers remain in sync, even if they're collaborating remotely all over the world.

The different stages of continuous integration are Integration, Delivery, and Deployment.

• Continuous Delivery: Translates to the practice of having a speedy and automatic delivery or release process once charges have been merged, and it is released to build clients.
• Continuous Deployment: When the product is actually released to clients

Examples of some continuous integration tools are:

• Jenkins
• CircleCI
• GitLab
• Travis

Continuous integration and delivery process. credits: Ronak Kumar Samantray

What Benefits Do CI/CD Have for OSS?

When a bunch of contributors are working on various aspects of a project from various perspectives and places, it must come together and not be in conflict. Additionally, fixing one issue shouldn't lead to the emergence of new issues elsewhere.

To accomplish all this, you must use some automated testing. So when testing, you should take into account many factors, such as:

• Whether you may implement modifications that overlap at the same time.
• Whether there are any conflicts.
• If the project is still able to compile after the changes are applied.
• If you make all the necessary changes, can you ship it?
• Does it work on all possible targets?

By ensuring that testing is constant, automated, and performed regularly, any problems that arise are swiftly fixed, and developers and users remain on the same page. And Continuous integration makes sure that any of these issues are minimized.

OSS Licenses an Legal issues

What is an Open Source License?

An open-source license is a sort of license for software that permits the use, modification, and/or sharing of the source code, blueprint, or design under specific terms and conditions.

Then end users or developers can review and modify the source code, blueprint, or design for their own use cases, curiosity, or troubleshooting requirements. Although it is not always the case, open-source licensed software is typically offered free of charge.

There are two types of software licenses that OSS projects generally use:

• Restrictive – the software remains open, but it has strict restrictions on any attempts to create proprietary closed goods. Changes to the code are also made available to future recipients, such as the GPL License.
• Permissive – these licenses don't demand updates and alterations to be publicly accessible, such as BSD and Apache fences.

Companies should consult with lawyers, either internal or external, to ensure that they do not violate copyrights and licenses when using code from open source projects.

There are many different licenses, so be careful. But once an organization establishes proper standard operating procedures, they must follow them for every project.

OSS Licenses help gives contributors a better idea about how to use and contribute to the source code.

Most Common Licenses

• GNU General Public License (GPL)
• MIT license
• Apache License 2.0
• BSD 3-Clause "New" or "Revised" license
• BSD 2-Clause "Simplified" or "FreeBSD" license
• GNU Library or "Lesser" General Public License (LGPL)
• Mozilla Public License 2.0
• Common Development and Distribution License

How to Choose a License for Your OSS Project

This is a crucial choice that has to be carefully considered because it may be difficult or even impossible to switch to a different license later in the project's existence.

Here are some things to consider when choosing one for your project:

• If you need a simple and permissive license, the MIT License is succinct and direct. It gives users practically unlimited access to your project. Examples of projects that use the MIT License include .NET and Rails.
• If you are more concerned about sharing improvements, almost everything can be done with your project under the GNU GPLv3, with the exception of disseminating closed source versions. Examples of projects employing this license include Ansible and Bash.

Read more about choosing the best license for your project suit here and here.

How to Build Better Open Source Software Projects

Understand that Leadership is not Control

An effective leader allows and encourages all participants to speak up and share their ideals while contributing. This often leads to more creative, high-quality work. So remember: loosen the reins when you can.

According to the well-known leadership paradigm known as the "Benevolent Dictator for Life" (BDFL), a project's controllers can only do so much if they take without giving back via teaching and moderating.

Also, if you're a maintainer, make sure you go through some training to learn how to be a good leader. Having a good mentor, for example, is vital in helping you acquire the information and skills required to become a good maintainer.

If the maintainer isn't helpful or supportive, new project participants will often move on to another project if they can't connect with an experienced contributor.

And finally, remember that an open-source project cannot succeed without trust. Reputations are built up over time, and new members should be cognizant of the past.

Why Many OSS Projects Fail

Most successful open source projects started off small and grew slowly. It's often hard to predict which projects will be successful and which won't.

Some of the reasons OSS project fail are:

1. They try to do the same thing as more mature programs.
2. They don't have good leadership.
3. There's a general lack of interest in their product/service.
4. They don't have enough developers
5. They don't have the correct license.

To combat these issues, here are some things to keep in mind:

• Make sure you have good and effective leadership, because this leads to more creative, high-quality work.
• Make sure your project has a well-defined governance structure and license.
• Encourage developers working on your project by providing resources and information to help them start contributing.

Diversity in OSS

The word "Open" in open source software (OSS) may be taken to mean a welcome, friendly environment. But this may only be a false promise if the project doesn't cultivate a welcoming atmosphere.

There are various forms of diversity, such as nationality and race, sex and gender identity, regional or geographic location, politics and belief systems, and so on.

It's important to respect and foster diversity in whatever ways you're able to do so. Some ways to foster diversity in the OSS space include:

• Respecting peoples beliefs and religions
• Not being biased against contributors for any reasons relating to race, sex, gender identity, location, beliefs, and so on.
• Valuing the contributors of all your contributors and engaging with them whenever possible.

How to Use GitHub for Hosting OSS Projects

Before GitHub, projects needed their own servers to host repositories. They also needed developers with extensive technical skills to set up, manage, and protect the repositories' integrity.

Developers can now primarily concentrate on the code by using GitHub or other Git hosting services like GitLab or Bitbucket.

Types of Repositories

There are two types of repositories on Git:

• Public Repositories that are accessible to everyone on the internet.
• Private Repositories, which are only accessible to you, people you explicitly share access with, and, for organization repositories, certain organization members.

Hands-on practice using GitHub for collaboration

Now we'll go through some basic steps, which, when you get them down, will provide you with the ultimate superpower in effective collaboration.

We will understand more fully by building a name biography website. So let's dive in:

Here's the Project Repo so you can follow along.

Step 1 – Fork the repository

This is to create a copy of the repository of the project in your gitHub account for more accessibility.

Then, click on the project link above and then fork the repository. To fork a repository, click the fork button at the top right corner of the GitHub website of the repo.

fork repository

Step 2 – Clone the repository

Cloning is creating a copy of the code online (your repository) on your local computer so you can work on it from there.

Cloning the repository on your computer is sometimes referred to as using a "local repository".

Click the code tab on the forked project on your GitHub and then click the copy code icon as show below:

clone repository

Now let’s go to your local computer. Open your favorite code editor (mine is VSCode) and open the inbuilt terminal. Then paste the code you copied after a 'git clone' command to clone this project repository to your local computer as shown below:

git clone <your-copy-code>

Now in your terminal, move to the generated project folder with the code below:

cd OSS-Contribution-Beginer

Step 3 – Create a branch from your local repository

Branches allow you to make changes without affecting other contributors' code and the main branch. it is always good to create your own branch when contributing to projects.

To do this is simple – just write the following code:

git branch ‘name-of-the-branch-you-want

e.g git branch caesar-name

Then you can switch to the branch you just created:

git checkout caesar-name

Step 4 – Make changes to the repository

In this scenario, our problem is to change the README.md to include your name, social media handle, and preferred emoji (you can browse how to get markdown emoji).

Scroll to the bottom of the README.md file. Add your name, social handles, and emoji to the list. Then save the changes.

Step 5 – ADD and COMMIT your changes

Adding and committing your changes is a way to save the changes you made into your local Git repository.

To achieve this, in your terminal run the following commands:

git add .

Then commit the code:

git commit –m “added my name bio”

Step 6 – Push it online

All we did in step five has been on your local computer or repository. Now it's time to push it to the original online repository on GitHub.

You can do this with the few lines of code below:

git push origin –u ‘your branch name’
i.e
git push origin –u caesar-name

Step 7 – Make a pull request (PR)

You can let people know about changes you've pushed to a branch in a GitHub repository by making a pull request.

Before your modifications are merged into the main branch, you can examine and validate the prospective changes with collaborators and the maintainer after you submit a pull request. You can even add follow-up contributions.

Go to your forked repository in GitHub online, see your resent changes that you just pushed, and click on compare and pull. Then click the create pull request button.

Pull request

pull request

Hurray! Congratulations. 🔥💡 You've successfully made your first open source contribution.

Summary

The open source ecosystem is a wide and interesting one, and you can benefit a lot from collaborating with others and making contributions.

In this article, you learned how open source projects work, what to consider when getting started, how to contribute, and how the different licenses work.

As always, I hope you enjoyed the article and learned something new. If you want, you can also follow me on LinkedIn or Twitter.

Cheers and see you in the next one! ✌️

Many developers use Git today. And they're usually familiar with basic Git concepts like:

• How to initiate a repository.
• How to create branches.
• How to stage/unstage changes.
• How to commit changes.
• How to push commits to remote.

However, many developers are confused about concepts like merging and resolving merge conflicts. In this article, we will learn how to resolve merge conflicts in a practical way. This means you will read, understand, and try it out while going through this article.

If you like to learn from video content as well, this article is also available as a video tutorial here: 🙂

If you are new to Git and want to learn all the basic concepts, here is a helpful crash course.

What are Devs Saying about "Merge Conflicts"?

Recently I conducted a poll on Twitter, LinkedIn, and YouTube, asking if developers are comfortable with resolving merge conflicts in Git. Guess what I found?

70%-80% of developers shared that they find it challenging to resolve a merge conflict in Git. So this means that "Resolving Merge Conflicts" is an important topic of discussion.

Poll Results - Are you comfortable resolving merge conflicts in Git?

What is Git Merge and What are Merge Conflicts?

Git is a version control system that keeps a history of all your file versions. You can go back to any of the versions at any time and retrieve an older version.

Suppose you have created a file called abc.txt and pushed it to a Git repository. At this point, the file has its current version associated with it. Now, if your co-worker changed the same file and pushed it back to the repository, the file has a new version associated.

Git Merge is a feature that allows you to keep the file's current content in sync with other previous versions. This is essential because anyone at any point in time should be working on the most recent content of the file without overriding any changes from the previous versions.

Git merge helps you merge changes from other developers before pushing a new change to the same file.

In the case of Git merge, we need to be aware of two things:

1. Changes: What type of operations occurred between two versions of a file? New content is added or removed, or existing content is updated.
2. Possibilities: There are two possibilities. The changes happened in the different regions of the file or the changes happened in the same region of the file. Same region means that developers have made changes around the same place (for example, paragraphs, lines, and so on) of a file.

Fortunately, Git automatically takes care of most of these cases using the auto-merge strategy. But when the changes have occurred in the same region of the file, Git won't perform an auto-merge. Instead, it leaves it to you to Resolve the Merge Conflicts.

Git Merge Conflicts: A Horror Story

Let's understand the above situations with a story of two developers, Alex and Tina.

One fine day,

• Alex pulled changes from the remote repository to his local repository.
• He changed the file called abc.txt, staged it, committed it, and finally pushed it back to the remote repository.
• In the meantime, Tina, unaware of Alex's changes in the abc.txt file, made some changes in the same region of the file and tried pushing it to the remote repository.
• Git is a version control system, so it warned Tina that she had changed the version older than what it was in the remote (as Alex's changes were already in the remote).
• Now, Tina needs to first pull the changes from the remote, update the file, and then try pushing again.
• Tina did this. However, in her wildest nightmare, she got the warning that auto-merge failed, and so she needs to now Resolve the merge conflicts.

Does this story ring any bells? Is the above story related to you? There's a chance that you've been in Tina's shoes in the past. If not, you will get there eventually! So, let's understand how Tina has to deal with this situation efficiently.

How to Resolve Merge Conflicts in Git

Resolving merge conflicts is not as tricky as it may sound. In 90% of cases, it is easier once you have a clear understanding of the changes and a peaceful mind.

Thought Process

Once Tina pulls the changes, Tina's local file has her changes plus Alex's changes. Now Tina can do one of these four things:

• She can keep Alex's changes and remove hers.
• She can remove Alex's changes and keep hers.
• She can keep both Alex's and her changes.
• She can remove both Alex's and her changes.

Alright, but which one she should be doing? That is entirely dependent on the project's needs and the use-cases. Tina will understand the incoming changes and do whatever is relevant to the situation.

So, what are incoming changes? How's Tina going to identify that? How does Tina make the changes? I know you have got many such questions. Let's get the answers to all of them by taking a couple of real-life examples in the section below.

Steps to Resolve Merge Conflicts in Git

Let's take a couple of real-life examples of merge conflicts, and learn how to resolve them.

At any point in time, if you want to learn these concepts interactively, please check out this section of the video I have mentioned at the beginning of this article.

Example 1: Changes are in the Same Region of the File

When Git cannot perform an auto-merge because changes are in the same region, it indicates the conflicting regions with special characters. The character sequences are like this:

• <<<<<<<
• =======
• >>>>>>>

Everything between <<<<<<< and ======= are your local changes. These changes are not in the remote repository yet. All the lines between ======= and >>>>>>> are the changes from the remote repository or another branch. Now you need to look into these two sections and make a decision.

The image below shows the content of a file indicating that auto-merge didn't occur and there is a conflict. The conflict is in the line where we have modified the file locally by adding a line - Sleep. But in the meantime, someone else pushed a change by adding the line - Gym in the same region.

So, the line - Sleep is marked as the local change and - Gym as the incoming changes from the remote repository or another branch.

Merge Conflict due to Changes in the Same Region

Based on your use case and project needs, you will make the call to resolve the conflict. If you need to keep only the line with - Sleep, you will keep that and remove the rest of the conflicting texts. In that case, the file content becomes:

- Eat
- Read
- Sleep

On the contrary, you can keep the line - Gym and remove the - Sleep changes:

- Eat
- Read
- Gym

If you need to keep both lines, remove the lines related to the conflict indicators:

- Eat
- Read
- Sleep
- Gym

If you think none of the changes are required, remove them all.

- Eat
- Read

It is entirely up to you to decide what changes are relevant to the situation. After your changes, you need to make sure that none of the conflict-indicating characters exist (<<<<<<<, =======, >>>>>>>) in the file. Once you settle with the changes, do the following:

Stage the changes:

git add <files>

Commit the changes with a message:

git commit -m "Message"

Finally, push the changes to the remote:

git push

That's all there is to it to resolve the merge conflict in this scenario.

Example 2: The File is Removed at the Remote/Other Branch

In removed file merge conflicts, a dev deletes a file in one branch while another dev edits the same file in another branch. In this case, you need to decide if you want to keep the file or if it was right to delete it.

To add the deleted file back to your branch, do this:

git add <file-name>

To go ahead with the deletion of the file, do this:

git rm <file-name>

Then commit your changes with a message:

git commit -m "Message"

Finally, push it:

git push

What's Next?

If you learn from the above two examples and practice them, you will be able to take care of most scenarios and resolve your merge conflicts. So, I recommend practicing them a couple of times.

If you face any new scenarios or get stuck in resolving a merge conflict, feel free to post a comment about it in the comment section of this video. I'll try my best to respond back!

Before we wrap up, a few tips for you:

• All the examples shown in this article assumes that you're using GitBash or any other Git CLI to resolve merge conflicts. You can use any other GUI tool to do the same.
• Always pull from remote/other related branches before you start any new logical work on your code. It will keep your branch up-to-date as much as possible and reduce the chances of conflicts.
• Always pull before a push to make sure you will not face any rejections from Git.
• Talk to your peers/co-developers when you are unable to make a call on what to keep vs. what to remove. Pair up to resolve any difficult merge conflicts.

That's all for now. I hope you found this article informative and insightful to help you with merge conflicts in Git.

Let's connect.

• Give a Follow on Twitter if you don't want to miss the daily dose of Web Development and Programming Tips.
• Check out my Opensource projects on GitHub.
• You can SUBSCRIBE to my YouTube channel if you want to learn JavaScript, ReactJS, Node.js, Git, and all about Web Development in a practical way.

See you soon with my next article. Until then, please take care of yourself, and stay happy.

Coding can be challenging, but it can become a lot easier if you have the right strategies and tools.

After all, as noted software engineer and writer Joel Spolsky says, "it is harder to read code than to write it."

One way to make your development projects more successful is with collaborative coding. This refers to the process of working on the code with a team or with another developer. In a project that uses collaborative coding, each team member helps build the code and checks it for bugs or errors.

Working in pairs or teams helps finished code contain fewer mistakes and bugs, and this results in better code quality and projects being completed more quickly.

It also enables faster debugging and greater project resiliency, as this setup makes it easier for other developers to take over in case one of the developers has to leave the project.

But collaborative coding won't produce all of these benefits by default. Making them happen comes down to how you implement your collaborative development strategy and how you execute it. Here are four points to consider when doing so.

You Need a Secure Development Process

Although having multiple sets of eyes checking a project's code should produce a net benefit for the code's security — it can also introduce a new type of vulnerability into the mix. This is because sharing code through a collaboration platform creates the possibility of a data breach.

Humans, after all, are the weakest link in the cybersecurity chain. So, the larger the team, the greater the odds that someone will make an unforced security error during development.

And things like exposed or stolen login credentials can endanger a project — especially one that is designed to handle sensitive information like banking and personal details.

This means that project managers must choose a collaboration platform that's built with security in mind. Some collaborative coding platforms already have built-in security features, but others do not. And different types of coding projects will call for different feature sets, so there's no one-size-fits-all solution.

There are plenty of collaborative coding platforms that may fit the bill, however. Teletype, for example, comes with end-to-end encryption and the option to use self-destructing messages.

Another popular option is Brackets, which comes with data protection when interacting with third-party plugins and has a mechanism for preventing unapproved access and privilege escalation.

Some teams or developers might use established collaboration platforms not specifically designed for coding. Microsoft Teams, for instance, can facilitate casual coding collaboration. And although it's not an inherently insecure system, it has weaknesses that developers can address with an additional Microsoft Teams Security solution.

These solutions include features like malware protection, URL protection, access control over confidential data, compliance tools, and security alerts – which all improve platform security significantly.

Regardless of the platform you choose, though, it is important to use security tools or to install third-party security solutions that ensure the best possible security for your project.

Choose the Right Platform for the Job

It's also important to recognize that security isn't the only consideration when you're choosing a collaborative coding platform.

It's also critical to choose one that will provide every team member with the tools and resources necessary to do their job. The right platform should meet the following criteria:

It's made for a specific programming language or ecosystem

There are many benefits in using a platform that is created for a specific programming language. First, it most likely has all of the tools necessary to efficiently work on a project in a particular language. And it won't have unnecessary features added to cater to other requirements and preferences.

A language-specific platform is also designed with best practices in mind for developers working with particular languages or frameworks. So, for example, when working with dynamic programming languages such as Go, Ruby, and Python, it is preferable to use a platform like Cloud9.

It's fast to setup

Ideally, everyone involved should already be familiar with the collaborative coding platform that you'll use. But if this isn't the case, it's important to choose one that is easy to learn with minimal to no configuration involved.

A platform that requires IDE, server, terminal, codebase, and library configuration along with other setup procedures is not the most suitable option for live coding between pairs or teams of developers.

It should have a customizable user interface

Programming is a heavily detail-driven job and developers tend to have their own preferences when it comes to the user interface so they can work easily and conveniently.

Forcing everyone to use a platform they are not comfortable with is not a good way to proceed with collaborative coding. So it helps to have the option to modify the UI or dashboard to some extent.

The bottom line is that the collaborative coding platform should be easy to use for everyone. Developers may be highly skilled people, but not everyone is a master of everything. Those who are collaborating should agree on a platform and working arrangement that works for everyone.

Define Clear Team Roles at the Outset

We can categorize collaborative coding into three general setups:

• pair programming
• mob programming, and
• code sharing.

And understanding the inner workings of each of these setups is important, as different coding projects require different setups.

But it's equally important to understand the roles of the team members in each setup and to define them before beginning to code.

As the phrase suggests, pair programming involves two participants. Usually, one serves as the driver and the other acts as the navigator. The driver writes the code while the navigator reviews the output.

In this setup, the driver is responsible for the tactical aspects of the job while the navigator sets the strategic direction of the code. The two may then switch their roles to have a more thorough look at what they have produced.

Mob programming is similar to pair programming but involves more than two people. To avoid making it a chaotic or disorganized arrangement, it is also important to have the driver-navigator role assignments.

It is slightly more complicated, though, because there are more than two developers who have to agree on how to assign the driver-navigator roles. This means that clear communication and mutual respect are crucial.

The code-sharing setup does not require a driver-navigator dynamic. Instead, the collaborating developers only share their respective code to allow each other to review, modify, debug, or add to each other's code.

This is the type of collaboration that open source developers tend to rely on because it allows newcomers to participate at will and existing developers to pause their work whenever they need to.

The participants here may work on the code together in real-time or asynchronously. What's important is that they have a reliable system for version control.

That's where version control systems like Git excel. They help teams to avoid doing duplicate work and make sure that all developers are reviewing, revising, or adding to the latest version of the code at all times.

Create Skill Balanced Teams for Best Results

While some would consider collaborative coding as an opportunity to learn from more experienced and proficient coders, that doesn't mean every collaborative project is conducive to that.

This is because for certain types of projects, having too much of a disparity in the skill level of team members can grind the whole project to a halt.

This is a problem that feeds one of the biggest criticisms of collaborative coding as a development method. When team members must contribute as equals but lack the skills to keep up, progress stalls. When time is of the essence, creating a skill-balanced team is the only option.

That said, collaborative coding can be an opportunity for collaborative learning, but only when deadlines aren't involved. In that scenario, team members can take their time to learn from the work of their more experienced peers. And in the end, everyone benefits from the experience.

But if the goal is to make the project a collaborative learning endeavor, it is important to make that clear from the get-go. Otherwise, the more experienced developers could feel like they've been duped into providing training instead of getting the project done. And that never ends well.

Conclusion

The advantages of collaborative coding are undeniable — but there are drawbacks to consider too.

So, before deciding to go into the collaborative route, it is important to carefully scrutinize the pros and cons as they relate to a specific project.

And for developers who wish to try their hand at collaborative coding, it's a good idea to get familiar with the popular tools and platforms used for such projects beforehand. That way, both the project planners and team members will get the most out of the collaborative process — but without encountering some of the issues that it can entail.

Featured photo by snowing 12 - stock.adobe.com

We launched our open source project in June 2021, and since then we've gotten more than 4500 stars for our repository.

Here are the strategies that worked for us. This is not an article about how to just get more stars for your repository. The article instead explains how to present your project well so that it is helpful for the open-source community.

Some of these points have also helped us get contributions from more developers. We have contributions from more than 100 developers now.

Fun fact: the graph above was generated using an app built with our tool. You can try it out here to generate a star history chart for your project.

Alright, let's dive into the strategies we used to raise awareness for our project.

Write a Good Readme

The README is the first thing that a visitor to your repository sees. It should be able to convey what your project does, how to install the project, how to deploy the project (if applicable), how to contribute, and how it works.

You can also use badges that are helpful for developers. We used https://shields.io/ for adding badges to our Readme.

Here is what our Readme looks like:

And here are some examples of projects with great README files:

1. https://github.com/nestjs/nest
2. https://github.com/typesense/typesense
3. https://github.com/airbytehq/airbyte
4. https://github.com/strapi/strapi

Focus on Documentation

We get more traffic to our documentation portal than our main website. A well-documented project is always loved by the community.

Open-source projects like Docusaurus make it super easy to build documentation portals that look great just out of the box. Adding links to the repository from the documentation can drive more visitors to your repository.

What to include in documentation

How to install/deploy the project

If the project has a compiled software as the final product, make sure to add installation instructions.

If the project is the codebase for a library such as an npm package or a Ruby gem, include details on how to import and use the library.

If the project needs to be or can be deployed on platforms like Kubernetes, Docker, Heroku, and others, include separate guides for each of the options.

Contributing guide

Apart from the contributing guide doc in the codebase, add one to the documentation, too. It should include guides for setting up a local environment on different platforms like Docker, Mac OS, Ubuntu, Windows, and so on.

Tutorials and code examples

If this is applicable, it can be really helpful. How to guides on using using the project will show other devs how they can actually get started. It can be code examples if the project is a library.

Architecture reference

It will be helpful for the contributors if the documentation has details on different components of the project.

For example, if the project has server and client components, include a diagram on how everything works together. Here is an example from ToolJet's documentation.

Here are some projects with great documentation:

1. https://docs.nestjs.com/
2. https://docs.n8n.io/
3. https://guides.rubyonrails.org/
4. https://plotly.com/python/
5. https://docs.mapbox.com/

Drive visitors from your website to GitHub

A lot of visitors checked out our repository after visiting our website first. Add banners, badges, and other incentives to your website so that visitors will check out your repository.

Add a CTA to your website and blog so that the visitors will check out your repository. Write about topics relevant to your audience. For example, if your project is used for logging errors, it might be a good idea to write about how to track errors in an application.

Publishing articles on platforms like freeCodeCamp, dev.to, Hashnode, and Hackernoon can also help you get more visibility for your blog posts. Some of these platforms allows cross-posting while some others are more suited to exclusive content.

Be active in developer communities

There are many discord/slack communities, forums, Reddit communities, and so on where developers usually hang out. Be active in these communities without making it look like self-promotion (which can get you banned for obvious reasons).

You can add value to the communities by participating in relevant discussions. For example, if you are building a charting library and if someone is asking a question about plotting charts using React, you can pitch in to help.

Remember, play nice. Do not just try to link to your project if it does not add any value to the discussion. The more you build up relationships by helping people, the more you'll be able to share info about your project in a natural, helpful way.

Trending repositories on GitHub

If you make it to the list of trending GitHub repositories, it can get your repository a lot more visibility.

When we made it to the trending list, we got more visitors to our repository and website.

There are trending lists for specific languages too. Many Twitter bots and other tools notify developers whenever there is a new repository that has made it to the trending list.

How to get on GitHub's trending list

The general principle should be that repositories with the most activity ( stars, visitors, issues, contributions, and so on ) will be added to the trending list.

GitHub hasn't publicly mentioned the criteria for selecting trending repositories, so we can only assume how it works.

Ask for feedback from relevant communities

Communities such as ProductHunt, Hackernews, Reddit communities, and others may find your project useful. This can bring in more visitors and stargazers to your repository.

Target only the relevant communities. If you think the majority of the members won't find your project interesting, it is not a relevant community. Spamming can cause more harm than good. Also, it's just not nice.

Grow a community around your project

Start a community on Discord or Slack where your users and contributors can hang out.

Communities can be helpful when the members are stuck with something and if they want to propose something new. If there is an active community, your future posts and announcements might get more reach.

We created the community on Slack since most of the developers have a Slack account. Don't use lesser-known platforms for building your community as it will take an additional step for the person to join the community.

Add a public roadmap

A public roadmap helps your users and contributors understand where your project is headed. It gives an overview of the short-term vision of the project.

There are many tools available for creating public roadmaps, but in most cases GitHub projects will be more than enough for creating a simple yet effective public roadmap.

Public roadmaps should include all major features and changes that are expected to be released in the next few months. Adding minor features and bugs as part of product roadmap can lead to a lot of noise, so avoid it as much as possible.

If you use GitHub projects, link to the relevant issues or discussions so that the community can comment their suggestions.

We have created one using GitHub projects that you can check out here.

Be Active on Twitter

Being active on posts related to your projects can create awareness, increase the number of followers on Twitter, and drive more visitors to your repository.

Participate in discussions that are related to your project. For example, if your project is a documentation framework, you can add a lot of value to threads that compare different documentation frameworks.

Make sure to link your repository on the project's Twitter profile. Also, add a tweet button to your GitHub repository.

Again, make sure you add value to the discussions. No one likes a spammer.

Respond to feedback

Open-source communities are usually very helpful and give a lot of feedback. Respond to all this feedback, as the person has taken their valuable time to help you improve your project.

Positive feedback helps you stay motivated, while negative feedback helps you rethink what you've done so far.

Do not try to avoid or ignore negative feedback. Be open-minded and consider carefully what the person has shared. Work on it if it aligns with your vision, otherwise politely explain.

Add relevant labels for contributors

Adding labels such as "good first issue" and "up for grabs" can attract more contributors to your repository.

There are many platforms such as https://goodfirstissue.dev/ that scan for issues tagged with relevant labels to help contributors discover new repositories and issues to contribute to.

Make sure you respond to contributors quickly. Contributors can be experienced developers as well as developers in the early stages of their careers or students. Try to help the first time contributors so they can onboard easily.

Wrapping Up

You landed on this article possibly because you have an interesting open-source project. I'd love to see your project. I'm available at navaneeth@tooljet.com and on Twitter.

Hope this article was helpful for you. We would really appreciate it if you can take a moment to check out our project, ToolJet, and give us any feedback you might have.

So, now that you've published your first open-source project, what next? If you're new to open source, you might think this is it. But the fun has just begun.

In fact, most of the work lies in maintaining your project and making it accessible to more users. This is one of the most important steps in the process and it's what enables an open-source project to have a successful run.

Maintaining OSS essentially means keeping the project up-to-date so that it is compatible with the latest version of the various third-party libraries, frameworks, and software that it uses.

It's also important to set up good security measures. Bugs are an inevitable part of any software development life cycle, so fixing bugs that pose a threat to security equally important.

A few days ago, I published my first open-source project, an npm package. So, now, it is important that I follow some best practices to make it lucrative.

Here, I'll be walking you through some of the steps to help you maintain an open-source project as I learn them.

Throughout this article, I'll be using GitHub (assuming that most projects are hosted and maintained there).

But if you happen to use any other VCS hosting site, you can still follow these steps to ensure your project's success.

Write Good Documentation

Documentation tells people what the software or code does, how to install it, how they can use it, and it provides a working example and contribution guides.

Note that even though the code is an open-source project, it still needs to have a license to let other people use, alter, or make additions within the defined scope. So, documentation is basically a rulebook or a guide to help people use your software.

Source

Incomplete documentation will make it difficult for people to get the gist and purpose of your code, making them hesitant to try it out no matter how good your project is.

So just make sure you have well-written documentation, along with any details about all the latest changes you've made to the project.

Automate Repetitive Tasks

Maintaining an open source project will typically involve many tasks that are repetitive, like scheduled maintenance, periodic updating of dependencies, continuous integration, and so forth.

Since these tasks are time-consuming, repetitive, and require no innovation, you can automate many of them.

Take updating dependencies, for example. It is common to make use of other packages and dependencies in your projects. But, at the same time, you can't afford to compromise your project's security/performance by using a dependency that is obsolete.

One tool that I find useful for this is the free WhiteSource Renovate. It automates dependency updates. So using a tool like Renovate to keep dependencies updated is a crucial task you shouldn't neglect. If you want to learn how to integrate WhiteSource Renovate into your project, continue reading the below section.

Automatic dependency updating with Renovate

Firstly, you'll need to integrate Renovate with your GitHub account. Then click install, and follow the steps as instructed.

While configuring, Renovate lets you decide if it should run on all the repositories by default or only on specific repositories. Select the option as you wish. (Note: If you want to Renovate to run on forked repositories, clicking Select All Repositories will skip forked repos by default. In such cases, you’ll have to manually add the forked repo(s)).

Soon after setting up Renovate with the required repositories, an onboarding PR will be submitted by the Renovate bot, which contains information like configuration summary and what packages/dependencies are supposed to be upgraded.

For demonstration purposes, I've forked a repo from my GitHub account that is supposedly a mobile application built on React Native. It is no longer maintained, so it'll serve as a good example to test on.

If you follow the above steps correctly, you should see an onboarding PR similar to this:

Initial PR

Merge PR

Once you merge the above pull request, the Renovate bot will start looking for outdated or stale dependencies that need to be updated and submit a PR for each dependency that needs to be updated.

Keep in mind that this tool doesn't trace vulnerabilities or issues, only available updates. But new dependencies often come with bug fixes, security improvements, and newly-added features.

Still, just because there's an update available doesn't mean you have to update it because chances are it might break your existing system due to a compatibility mismatch or something similar. So it's important to review the update before merging the PR.

To help you make sound decisions regarding whether you want to upgrade a package or not, the PR includes details about the adoption rate and test passing rate, which effectively determines the overall confidence level.

It also pulls the latest release notes from the dependency repository, which would otherwise require you to manually navigate to the repo to find what's new.

Always Address Issues

One good way to make sure that your project continuously improves is to address issues opened by your peers.

No one will show interest in contributing to an open-source project if it doesn't address potential bugs, security issues, or feature addition.

You can set up a CI script that assigns a label when an issue is opened and then assign it to the contributors maintaining the project accordingly. This will result in issues being reviewed at a rapid rate and will also help contributors find new fixes and/or feature additions.

Spread the Word About Your Project

You've published an excellent open source project, yet you don't see anyone using or contributing to the project. The primary reason for this could be that people haven't found out about your project.

To get the ball rolling, you should make sure your project gets all the exposure it can. One effective way to do this is by sharing your work on social media, wherever people are active who might be interested in it.

You can also get involved in discussions on topics related to your projects on Q&A platforms, like Stack Overflow and Reddit. Then sharing your project will be a natural thing to do.

Attract Helpful Contributors

Following the above steps will help you get started. But once your project starts growing, it’ll need more contributors that are willing to maintain the project.

This is only possible when you build up a strong contributor base. To increase the people helping you maintain the project, you can set up rewards for contributions, like giving out swag to people who satisfy certain requirements.

People will also be encouraged to contribute if they feel a sense of pride and ownership of the project. So make sure everyone gets due credit for their contributions, big or small.

Positive actions like this can also potentially enable new contributors to share their work with their friends/colleagues, indirectly helping your project gain more exposure/users/contributors.

Wrapping up

At the end of the day, the value your project provides is what determines how many people contribute to and use it. So when you're creating an open-source project, keep usability and impact in the front of your mind. How will your project make others’ lives easier? What problem(s) does it solve?

These are the steps you should to take to successfully maintain an open-source project. Do you recommend any other important practices that can add value to this list? If yes, do share them with me so we can all learn more about the open-source culture.

If you found this article helpful, feel free to share it with your friends and colleagues, you can follow me on Twitter for more such stuff :)

Cheers!

You might feel uncertainty when encountering the Git commit message, unsure how to properly summarize the changes you've made and why you've made them. But the earlier in your career you can develop good committing habits, the better.

Have you ever wondered how you can improve your Git commit messages? This guide outlines steps to elevate your commit messages that you can start implementing today.

This article assumes you already understand basic Git workflow. If not, I suggest reading through the Git Handbook.

It is also important to note that you should follow your team's conventions first and foremost. These tips are based on suggestions based upon research and general consensus from the community. But by the end of this article you may have some implementations to suggest that may help your team's workflow.

I think git enters a whole other realm the moment you start working in teams -- there are so many cool different flows and ways that people can commit code, share code, and add code to your repo open-source or closed-source-wise. — Scott Tolinski, Syntax.fm.

Why should you write better commit messages?

I challenge you to open up a personal project or any repository for that matter and run git log to view a list of old commit messages. The vast majority of us who have run through tutorials or made quick fixes will say "Yep... I have absolutely no idea what I meant by 'Fix style' 6 months ago."

Perhaps you have encountered code in a professional environment where you had no idea what it was doing or meant for. You've been left in the dark without code comments or a traceable history, and even wondering "what are the odds this will break everything if I remove this line?"

Back to the Future

By writing good commits, you are simply future-proofing yourself. You could save yourself and/or coworkers hours of digging around while troubleshooting by providing that helpful description.

The extra time it takes to write a thoughtful commit message as a letter to your potential future self is extremely worthwhile. On large scale projects, documentation is imperative for maintenance.

Collaboration and communication are of utmost importance within engineering teams. The Git commit message is a prime example of this. I highly suggest setting up a convention for commit messages on your team if you do not already have one in place.

The Anatomy of a Commit Message

Basic:

git commit -m <message>

Detailed:

git commit -m <title> -m <description>

5 Steps to Write Better Commit Messages

Let's summarize the suggested guidelines:

1. Capitalization and Punctuation: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase.
2. Mood: Use imperative mood in the subject line. Example – Add fix for dark mode toggle state. Imperative mood gives the tone you are giving an order or request.
3. Type of Commit: Specify the type of commit. It is recommended and can be even more beneficial to have a consistent set of words to describe your changes. Example: Bugfix, Update, Refactor, Bump, and so on. See the section on Conventional Commits below for additional information.
4. Length: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters.
5. Content: Be direct, try to eliminate filler words and phrases in these sentences (examples: though, maybe, I think, kind of). Think like a journalist.

How to Find Your Inner Journalist

I never quite thought my Journalism minor would benefit my future career as a Software Engineer, but here we are!

Journalists and writers ask themselves questions to ensure their article is detailed, straightforward, and answers all of the reader's questions.

When writing an article they look to answer who, what, where, when, why and how. For committing purposes, it is most important to answer the what and why for our commit messages.

To come up with thoughtful commits, consider the following:

• Why have I made these changes?
• What effect have my changes made?
• Why was the change needed?
• What are the changes in reference to?

Assume the reader does not understand what the commit is addressing. They may not have access to the story addressing the detailed background of the change.

Don't expect the code to be self-explanatory. This is similar to the point above.

It might seem obvious to you, the programmer, if you're updating something like CSS styles since it is visual. You may have intimate knowledge on why these changes were needed at the time, but it's unlikely you will recall why you did that hundreds of pull requests later.

Make it clear why that change was made, and note if it may be crucial for the functionality or not.

See the differences below:

1. git commit -m 'Add margin'
2. git commit -m 'Add margin to nav items to prevent them from overlapping the logo'

It is clear which of these would be more useful to future readers.

Pretend you're writing an important newsworthy article. Give the headline that will sum up what happened and what is important. Then, provide further details in the body in an organized fashion.

In filmmaking, it is often quoted "show, don't tell" using visuals as the communication medium compared to a verbal explanation of what is happening.

In our case, "tell, don't [just] show" – though we have some visuals at our disposal such as the browser, most of the specifics come from reading the physical code.

If you're a VSCode user, download the Git Blame extension. This is a prime example of when useful commit messages are helpful to future developers.

This plugin will list the person who made the change, the date of the changes, as well as the commit message commented inline.

Imagine how useful this could be in troubleshooting a bug or back-tracing changes made. Other honorable mentions to see Git historical information are Git History and GitLens.

Conventional Commits

Now that we've covered basic commit structure of a good commit message, I'd like to introduce Conventional Commits to help provide some detail on creating solid commit messages.

At D2iQ, we use Conventional Commit which is a great practice among engineering teams. Conventional Commit is a formatting convention that provides a set of rules to formulate a consistent commit message structure like so:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The commit type can include the following:

• feat – a new feature is introduced with the changes
• fix – a bug fix has occurred
• chore – changes that do not relate to a fix or feature and don't modify src or test files (for example updating dependencies)
• refactor – refactored code that neither fixes a bug nor adds a feature
• docs – updates to documentation such as a the README or other markdown files
• style – changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on.
• test – including new or correcting previous tests
• perf – performance improvements
• ci – continuous integration related
• build – changes that affect the build system or external dependencies
• revert – reverts a previous commit

The commit type subject line should be all lowercase with a character limit to encourage succinct descriptions.

The optional commit body should be used to provide further detail that cannot fit within the character limitations of the subject line description.

It is also a good location to utilize BREAKING CHANGE: <description> to note the reason for a breaking change within the commit.

The footer is also optional. We use the footer to link the JIRA story that would be closed with these changes for example: Closes D2IQ-<JIRA #> .

Full Conventional Commit Example

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz. 

BREAKING CHANGE
Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Closes D2IQ-12345

To ensure that these committing conventions remain consistent across developers, commit message linting can be configured before changes are able to be pushed up. Commitizen is a great tool to enforce standards, sync up semantic versioning, along with other helpful features.

To aid in adoption of these conventions, it's helpful to include guidelines for commits in a contributing or README markdown file within your projects.

Conventional Commit works particularly well with semantic versioning (learn more at SemVer.org) where commit types can update the appropriate version to release. You can also read more about Conventional Commits here.

Commit Message Comparisons

Review the following messages and see how many of the suggested guidelines they check off in each category.

Good

• feat: improve performance with lazy load implementation for images
• chore: update npm dependency to latest version
• Fix bug preventing users from submitting the subscribe form
• Update incorrect client phone number within footer body per client request

Bad

• fixed bug on landing page
• Changed style
• oops
• I think I fixed it this time?
• empty commit messages

Conclusion

Writing good commit messages is an extremely beneficial skill to develop, and it helps you communicate and collaborate with your team. Commits serve as an archive of changes. They can become an ancient manuscript to help us decipher the past, and make reasoned decisions in the future.

There is an existing set of agreed-upon standards we can follow, but as long as your team agrees upon a convention that is descriptive with future readers in mind, there will undoubtedly be long-term benefits.

In this article, we've learned some tactics to level up our commit messages. How do you think these techniques can improve your commits?

I hope you've learned something new, thanks for reading!

Connect with me on Twitter @ui_natalie.

For the longest time as a beginner I did nothing with my account. But then, becuase of my passion in tech, I started following other developers and checking out their work on GitHub. And I noticed something they had in common: they all had cool projects and contributed to open source, but their projects also had detailed README files.

So my interest in what a README was grew, and I decided to try and add one in my projects, too. I won't lie – I did it in a hurry without any knowledge of how it should be done. And honestly it wasn't great at all. Check it out HERE.

And that was how it stayed for a period of time. But with practice and continuous learning I was able to change to some better documentation like THIS, which improved engagement with the project and helped other devs get involved.

It is also important to note that a good README will help you stand out among the large crowd of developers who put their work on GitHub.

In this article, we'll learn more about what a README file is and how to write one. First let's understand what we mean by a README file.

What is a README File?

In simple words, we can describe a README file as a guide that gives users a detailed description of a project you have worked on.

It can also be described as documentation with guidelines on how to use a project. Usually it will have instructions on how to install and run the project.

It is essential for you as a developer to know how to document your project by writing a README because:

• It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
• It will make your project standout from a bunch of others. Also be sure your project is good too.
• It will help you focus on what your project needs to deliver and how.
• It will improve your writing skills, just as Friedrich Nietzsche said:

  A good writer possesses not only his own spirit but also the spirit of his friends.

While working on a project, keep in mind that you will need other developers to understand your code and what it does. So accompanying it with an extra guide will be really helpful.

For instance, my earlier shared example of my first project does not have a good README. And even though the project was amazing, it would've been hard for a beginner to understand exactly what was expected when they cloned my repo. Who knows maybe it could've even been a coded virus.

With a project like this on GitHub, no matter how amazing it is, other devs won't be eager to work on it and try to figure it out without a good README.

Now, have a look at this project. Here, you are able to understand what the project does, what it entails, and how to get started if you need to use or want to contribute to the project.

You see, that's how powerful a well written README is and how it can change you project.

So, let's get started on how to write one for you too.

How to Write a Good README – a Step by Step Guide

A very important thing to note is that there's not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.

From research and studying various README files, for sure there are some best practices that I have found. And that's what I will be sharing. As I usually tell my self:

Every day is a learning day.

So as you progress and advance in your career, you will develop your own ideas about what makes a good README and how to improve on it. Perhaps you'll even come up with your own unique guide.

Before we get started, it is also important to note that when you're writing your project's README, it should be able to answer the what, why, and the how of the project.

Here are some guide questions that will help you out:

• What was your motivation?
• Why did you build this project?
• What problem does it solve?
• What did you learn?
• What makes your project stand out? If your project has a lot of features, consider adding a "Features" section and listing them here.

What to Include in your README

1. Project's Title

This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.

2. Project Description

This is an important component of your project that many new developers often overlook.

Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.

The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

• What your application does,
• Why you used the technologies you used,
• Some of the challenges you faced and features you hope to implement in the future.

3. Table of Contents (Optional)

If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.

4. How to Install and Run the Project

If you are working on a project that a user needs to install or run locally in a machine like a "POS", you should include the steps required to install your project and also the required dependencies if any.

Provide a step-by-step description of how to get the development environment set and running.

5. How to Use the Project

Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected.

You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project.

Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.

6. Include Credits

If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles and social media too.

Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.

This is just a way to show your appreciation and also to help others get a first hand copy of the project.

7. Add a License

For most README files, this is usually considered the last part. It lets other developers know what they can and cannot do with your project.

We have different types of licenses depending on the kind of project you are working on. Depending on the one you will choose it will determine the contributions your project gets.

The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes. If you need help choosing a license, use check out this link: https://choosealicense.com/

Up to this point what we have covered are the minimum requirements for a good README. But you might also want to consider adding the following sections to make it more eye catching and interactive.

Additional README Sections

8. Badges

Badges aren't necessary, but using them is a simple way of letting other developers know that you know what you're doing.

Having this section can also be helpful to help link to important tools and also show some simple stats about your project like the number of forks, contributors, open issues etc...

Below is a screenshot from one of my projects that shows how you can make use of badges:

The good thing about this section is that it automatically updates it self.

Don't know where to get them from? Check out the badges hosted by shields.io. They have a ton of badges to help you get started. You may not understand what they all represent now, but you will in time.

9. How to Contribute to the Project

This mostly will be useful if you are developing an open-source project that you will need other developers to contribute to. You will want to add guidelines to let them know how they can contribute to your project.

Also it is important to make sure that the licence you choose for an open-source projects is correct to avoid future conflicts. And adding contribution guidelines will play a big role.

Some of the most common guidelines include the Contributor Covenant and the Contributing guide. Thes docs will give you the help you need when setting rules for your project.

10. Include Tests

Go the extra mile and write tests for your application. Then provide code examples and how to run them.

This will help show that you are certain and confident that your project will work without any challenges, which will give other people confidence in it, too

Extra points

Here are a few extra points to note when you're writing your README:

• Keep it up-to-date - It is a good practise to make sure your file is always up-to-date. In case there are changes make sure to update the file where necessary.
• Pick a language - We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn't familiar with English.

Wrap Up

There you have it, everything you need to improve your README files, or even get you started with writing your first one.

At this point I am confident that you are in a position to add an interactive and inforamative guide to your next project or even an existing one and make your project standout.

There are many tools which you can also use to automatically generate a README for your project, but it's always a good practice to try it on your own before moving to automation. In case you want to check them out, they include:

• Make a README
• README Generator
• README

If you have read this far I really appreciate it. If you enjoyed this article and found it helpful, please share it so you can help another developer improve their projects.

I would love to see your newly crafted README file. Be sure to share a link with me via any of the links below:

Connect With me at Twitter | YouTube | LinkedIn | GitHub

Do share your valuable opinion, I appreciate your honest feedback!

Enjoy Coding ❤