Coders Headquarters

:wave: Introduction

Coders Headquarters (CodersHQ) is a social platform for developers to grow, network, challenge themselves, and gain points by contributing and helping others in this community. This platform was built by the community and for the community. The essence of CodersHq is to inspire everyone to learn to code, share knowledge and learn together.

Currently the platform is at the alpha stage with a lot of the foundations being set. It is built using django and deployed using docker.

📄 The Docs

Have a look at the docs, we document everything over there. We plan to migrate from the docs to something more established, like readthedocs, once we have enough material to work with.

We also document the tasks in notion and you can have a look at the issues section to find out what we are working on.

⚙️ Quick Setup

Make sure you have Docker version 2+ and then do the following to build the stack and update the databse :

$ docker-compose -f local.yml build
$ docker-compose -f local.yml run --rm django python manage.py makemigrations
$ docker-compose -f local.yml run --rm django python manage.py migrate
$ docker-compose -f local.yml run --rm django python manage.py createsuperuser

Follow the rest of the README for more information and use /admin to edit and create challenges.

🧑‍💻 Getting Up and Running Locally With Docker

The steps below will get you up and running with a local development environment. All of these commands assume you are in the root of your generated project.

Note

If you're new to Docker, please be aware that some resources are cached system-wide and might reappear if you generate a project multiple times with the same name.

Prerequisites

• Docker; if you don't have it yet, follow the installation instructions;
• Docker Compose; refer to the official documentation for the installation guide.
• (Windows) This repository can run on windows and was tested on WSL2. Once you have WSL2, and a linux kernel, installed and running you need to install docker and you should be good to go. (Tested on Docker version 20.10.7, build f0df350 and Windows OS Build: 19042.1052)

🏗️ Build the Stack

This can take a while, especially the first time you run this particular command on your development system::

$ docker-compose -f local.yml build

Generally, if you want to emulate production environment use production.yml instead. And this is true for any other actions you might need to perform: whenever a switch is required, just do it!

Run the Stack

This brings up both Django and PostgreSQL. The first time it is run it might take a while to get started, but subsequent runs will occur quickly.

Open a terminal at the project root and run the following for local development::

$ docker-compose -f local.yml up

You can also set the environment variable COMPOSE_FILE pointing to local.yml like this::

$ export COMPOSE_FILE=local.yml

And then run::

$ docker-compose up

To run in a detached (background) mode, just::

$ docker-compose up -d

Execute Management Commands

As with any shell command that we wish to run in our container, this is done using the docker-compose -f local.yml run --rm command: ::

$ docker-compose -f local.yml run --rm django python manage.py migrate
$ docker-compose -f local.yml run --rm django python manage.py createsuperuser

Here, django is the target service we are executing the commands against.

(Optionally) Designate your Docker Development Server IP

When DEBUG is set to True, the host is validated against ['localhost', '127.0.0.1', '[::1]']. This is adequate when running a virtualenv. For Docker, in the config.settings.local, add your host development server IP to INTERNAL_IPS or ALLOWED_HOSTS if the variable exists.

Basic Commands

Setting Up Your Users

• To create a normal user account, just go to Sign Up and fill out the form. Once you submit it, you'll see a "Verify Your E-mail Address" page. Go to your console to see a simulated email verification message. Copy the link into your browser. Now the user's email should be verified and ready to go.

• To create an superuser account, use this command:

    $ python manage.py createsuperuser

For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.

Type checks

Running type checks with mypy:

    $ mypy codershq

Test coverage

To run the tests, check your test coverage, and generate an HTML coverage report:

    $ coverage run -m pytest
    $ coverage html
    $ open htmlcov/index.html

Running tests with py.test

    $ pytest

Celery

This app comes with Celery.

To run a celery worker:

    cd codershq
    celery -A config.celery_app worker -l info

Please note: For Celery's import magic to work, it is important where the celery commands are run. If you are in the same folder with manage.py, you should be right.

Email Server

In development, it is often nice to be able to see emails that are being sent from your application. For that reason local SMTP server MailHog with a web interface is available as docker container.

Container mailhog will start automatically when you will run all docker containers. Please check cookiecutter-django Docker documentation for more details how to start all containers.

With MailHog running, to view messages that are sent by your application, open your browser and go to http://127.0.0.1:8025

Stargazers ⭐

Thanks to all of our Stargazers ⭐ 🔭 who is supporting CodersHQ project

Contributors ✨

We would like to thank and appreciate our extraordinary contributors :clap:

Rashed Suwaidi 💻 🎨 🪄 🚧🔬🔧

Abdulrahman Alblooshi 💻 🎨

Abdulkarim Suleiman 💻 ⚡

Musab 💻

DerpySmurf 💻

arsxl 💻

haralali 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!

Project Documentation

Get Started

Documentation can be written as rst or md files in the codershq/docs/src.

To build and serve docs, use the commands:

docker-compose -f local.yml up docs

Changes to files in docs/src will be picked up and reloaded automatically.

MdBook is the tool used to build documentation.

CI

Coders HQ has a CI workflow with github-pages in the github-pages branch which executes whenever a push happens to main like.

An example workflow .github/workflows/gh-pages.yml with GitHub Actions for GitHub Pages. For the first deployment, we have to do this operation: First Deployment with GITHUB_TOKEN - peaceiris/actions-gh-pages

name: github pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: 'latest'
        
      - run: mdbook build
        working-directory: ./docs
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main'}}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/book

Use a specific version of mdBook

Set mdbook-version: '0.4.10' to use version 0.4.10 of mdBook.

- name: Setup mdBook
  uses: peaceiris/actions-mdbook@v1
  with:
    mdbook-version: '0.4.10'

This action fetches the latest version of mdBook by mdbook — Homebrew Formulae

Contributing to CodersHQ

We welcome your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the code
• Submitting a fix
• Proposing new features
• Becoming a maintainer

We Develop with Github

We use github to host code, to track issues and feature requests, as well as accept pull requests.

We Use Github Flow, So All Code Changes Happen Through Pull Requests

Pull requests are the best way to propose changes to the codebase (we use Github Flow). We actively welcome your pull requests:

• Fork the repo and create your branch from master.
• If you've added code that should be tested, add tests.
• If you've changed APIs, update the documentation.
• Ensure the test suite passes.
• Make sure your code lints.
• Issue that pull request!

Any contributions you make will be under the MIT Software License

In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.

Report bugs using Github's issues

We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!

Write bug reports with detail, background, and sample code

This is an example of of a bug report, and I think it's not a bad model. Here is another example.

Great Bug Reports tend to have:

• A quick summary and/or background
• Steps to reproduce
• Be specific!
• Give sample code if you can. My stackoverflow question includes sample code that anyone with a base R setup can run to reproduce what I was seeing
• What you expected would happen
• What actually happens
• Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
• People love thorough bug reports. I'm not even kidding.

Use a Consistent Coding Style

From Facebook’s Guidelines

License

By contributing, you agree that your contributions will be licensed under its MIT License.

References

This document was adapted from the open-source contribution guidelines for Facebook's Draft

Platform

This document lists the more import features of Coders HQ. The list and details should be updated and match the live version of CHQ.

User System 👤

There should be a way for users to join through the landing page. The creation of users should be done using the industry standard when dealing with password and user data. Users should be able to look into their own details within their own profile page.

Chat Feature 💬

The website should have a way for users to communicate with each other and this feature should be self contained, i.e, it should not be an API to another external server but should be part of the docker stack. This feature can be a simple direct message chat function where all the data is saved in a local database. The user should be able to view his/her history and communicate with other users.

Scoring Feature 📶

There should be a basic scoring system where a user is scored continuously based on the following:

• Open source contribution, i.e. github score. This is currently in effect but should be improved
• Hackathon contribution (more details in the hackathon section)
• Challenge engagement and completion (more details in the challenge section)
• General activity with other users (social score)

Challenges 📜

Challenges are defined as a method for users to join an event where a specific problem is set by an entity with a time limit. Then users can attempt to solve the problem and upload their work for the admins/companies to select the winners.

Challenges can also be broken down into smaller parts, called sprints, each of which comes with its own time limit.

Challenges should have the following features:

• Optional multiple sprints each sprint can be more specific
• Can join with a team or as a single user
• Companies should have a lot of freedom when creating challenges
• companies should be able to do the following:
  • add logo
  • choose number of sprints
  • allocate prize
  • give/ recommend cloud provider computational power
• If a cloud provider is chosen then time must be allocated for the users to get used

Hackathons 🏆

Hackathons are similar to challenges, however, they will have a much smaller time-frame.

Blogging Feature ✍️

There should be a page where admins can create entries to a blog and have users like it and save it.

Companies System 🏢

Companies can be created by users and each company should have a specific set of privileges that users don't. These are:

• To create/edit their own hackathons
• To create/edit their own challenges
• To view hackathon/challenge contributions and select desired winners

Landing Page

The landing page should be a single page with basic information on the website and a login/signup redirect. The design of the landing page should be similar to the current draft landing page

Dashboard

The website should be built similar to a dashboard where the users have the ability to navigate to any section on the website and view new messages as a notification. The design should be intuitive and based on modern aesthetics

What is in the dashboard

These are the items that need to be part of the dashboard

• score
• basic info (maybe a card)
• number of live hackathons
• number of completed challenges
• news
• Upcoming events
• Interactions with user’s blog posts/comments

Email System 📩

The email should be integrated with django and an email should be sent when a user joins (this currently works using mailhog as a test bed). Admins should also have an easy way to send emails to multiple users or a single user.

Challenges

Introduction

Challenges should be a process and a tool for private companies to create challenges and post them to CHQ (Coders Headquarters) so that users would be able to enter and potentially win a reward.

Requirements

Level 1 Requirements

These are the requirements that must be met when creating the challenge section.

• Companies should be able to create challenges
• Challenges should be viewed publicly in the website
• Participants should be able to choose a challenge, or multiple challenges, and participate in them
• Participants should be able to send their solution to the challenges
• Companies should be able to view participants’ challenge entries
• Companies should be able to communicate with participants
• Companies should be able to send participants custom messages
• Companies should be able to select challenge winners

Level 2 Requirements

These requirements are softer requirements yet require a very good reason not to meet any one of these.

Questions: These are yet unanswered questions. When answered these should be striked through and pushed into the relevant section.

• Should we save the interaction between users and companies?
• How many attempts should we give users?
• How often should we allow users?
• Should we give score to winners only?
• How should we score winners?

Function Blocks

This section deals with breaking down the challenges into smaller blocks. Each block deals with its own specific problem while taking into consideration the flow of information to the next and previous block. Challenge Viewing and Communication Block This block deals with the flow of communication between the companies and the public. It also deals with the public viewing the challenges.

Ideas to view challenges

Challenge Board: A place where challenges are posted, maybe sorted based on difficulty/estimated time to completion. Users can view all challenges and select a challenge based on their interest.

By notification: Users can have challenges sent to them. Maybe they choose what interests them and have notification pop up if the challenge suits their interests. Challenge Creation Block This block deals with creating challenges by companies and putting it out to the public. Challenge Ranking and Acceptance Block This block deals with ranking participants and the ways/methods a winner[s] can be chosen. Challenge Participation Block This block deals with participating in a challenge.

Scoring

Coders HQ main tool would be the ranking system. This will rank coders in the website in terms of their activities and achievements in and out of CHQ. This is a highly anticipated tool.

It is recommended that the scoring mechanism includes the following : (Pluralsight ranking, Codechef ranking, Hacker rank ranking) : it will be awesome, if we can pull information from these websites to build a more contextual ranking system.

It will be awesome also to find a mechanism to add all certificated gained from educational websites + coders HQ and transform them to points + make the certificates visual. This can be done through the following:

1. Create 3 different categories, and assign a number of points for every category, for example category 1 : Short seminars from CHQ, Category 2 : Nano-degrees (Coursera + Udemy + edx) + corporations degrees (Microsoft + Oracle + AWS etc.), Category 3 longer degrees (6-18+ months types of degrees)
2. Create a mechanism where individuals can submit their certificates, and assign a number of points for every certificate.
3. Each point in the coders HQ is equal to 1 Peacock coin/token

Chat

Coders HQ should have a chat feature. The chat should allow people to meet and connect together and help form teams easily and effectively.

User System

This encompasses everything related to the user in terms of account creation, signing in and logiggn out. All the user data should be displayed in a dashboard where other users/entities can view their basic information.

As a milestone, we would like to also add the aspect of social sign in through (Google, Linkedin and Github accounts) – Additional to that we would like to pull some of the open information and display it on the individual dashboard.

Website Pages

We need to design and create multiple pages. These are listed in the following table according to the priority. Priority is higher for pages that need to be completed sooner.

Priority

Content

Landing page

The landing page should have the following items

• Navigation bar
  • sign in and sign up button
  • link to
    • docs
    • Github source code
    • how to contribute
• join button or email
• general information

Profile page

The following items should be in the profile page:

• GitHub score
• generic personal information
• hackathon joined/completed
• challenges joined/completed
• news preference

Dashboard

The following items should be in the dashboard page:

• github score (number)
• github history (chart)
• challenges (model)
• hackathon (model)
• news (simple model)
• Skillset (progress bar, number)

Coders HQ FAQ ❓

What facilities and services can coders(hq) provide for individuals that wish to learn how to become programmers or improve their current skills?

• One of the initiatives of coders HQ is (HQ) learn, which is an initiative that focuses on developing coders skills in multiple fields, hands-on workshops range from a beginner level to intermediate to expert level.

How do I apply for internships/programs?

• We will announce in the next period through our discord channel on internship openings either through the coders HQ or its partners.

Where can I find information on events/workshops?

• Currently most of the announcements for upcoming events will be through the Discord announcement channel, social media channels will be activated soon. We will drop a message when Coders HQ social media outlets are released.

Schedule/Calendar currently available anywhere?

• Coders HQ will announce its various programs 1 week in advance for the next period. In a form of a newsletter through the announcement channel. Individuals will have the chance to RSVP.

Do you offer certificates of attendance/participation?

• Starting from January 2022, coders HQ will be offering attendance certificates for its various hands-on workshops.

Is coders(hq) open to the public? How can I reserve a room or space to work inside?

• Coders HQ will open its doors officially soon for the community to come and book a coding work station. The benefit of this relies in facilitating the networking between the community more often, the mechanism of booking a work station will be announced soon.