chore: Base of Isshub project¶
Description¶
Abstract
========
The base of the project, including setup files, README, LICENSE and
gitignore.
Motivation
==========
Everything needs a starting point.
Rationale
=========
Readme
------
Describe the projects, the why and the how.
Actually only includes the main abstract parts of of the README, in
restructured text.
Format
''''''
The choice of this format was made to ease the integration with sphinx
to build the documentation.
Sections
''''''''
The README includes these sections:
- Abstract: To explain in a few words what this repository is.
- Motivation: To explain why a new version of isshub is needed.
- Rationale: The choices made before starting.
setup
-----
Base setup for the project, with version "0" (nothing inside for now).
setup.cfg
'''''''''
I chose the `setup.cfg` way of doing things because configuring a
project must be, in my opinion, declarative, and not code.
This will also allow other tools to have their configuration in the same
place.
License
-------
I'm not sure yet so for now it will be MIT. So this commit also includes
the LICENSE file, and defines it in `setup.cfg`
Makefile
--------
To help usage of the different tools that will be added, `make` is a
common and useful tool. So here it's base version with a few commands:
- help: Show the list of commands
- install: Install the project in the current environment, with its
dependencies
- dev: Install the project in the current environment, with its
dependencies, including the ones needed in a development environment
- dev-upgrade: Upgrade all default+dev dependencies defined in
setup.cfg
- dist: Build the package
Info¶
- Hash
663f485247adbd4df9b50dec328b6607887e0689
- Date
2019-05-27 17:14:11 +0200
- Parents
chore(git): Initial empty commit [007e5a99] — 2019-05-25 15:02:25 +0200
- Children
docs: Documentation generation [91e6919e] — 2019-05-27 17:14:11 +0200
- Branches
- Tags
(No tags)
Changes¶
.gitignore¶
- Type
Added
- Stats
+116 -0
@@ -0,0 +1,116 @@
+# Created by IntelliJ .ignore support plugin (hsz.mobi)
+
+# IntelliJ project files
+.idea
+*.iml
+out
+gen### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+# Doc from code
+docs/source/
+# Got 2 RST
+docs/git/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
LICENSE¶
- Type
Added
- Stats
+21 -0
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2019] [Stéphane "Twidi" Angel]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
Makefile¶
- Type
Added
- Stats
+46 -0
@@ -0,0 +1,46 @@
+PROJECT_NAME := $(shell python setup.py --name)
+PROJECT_VERSION := $(shell python setup.py --version)
+
+BOLD := \033[1m
+RESET := \033[0m
+
+default: help
+
+.PHONY : help
+help: ## Show this help
+ @echo "$(BOLD)Isshub Makefile$(RESET)"
+ @echo "Please use 'make $(BOLD)target$(RESET)' where $(BOLD)target$(RESET) is one of:"
+ @grep -h ':\s\+##' Makefile | column -tn -s# | awk -F ":" '{ print " $(BOLD)" $$1 "$(RESET)" $$2 }'
+
+.PHONY: install
+install: ## Install the project in the current environment, with its dependencies
+ @echo "$(BOLD)Installing $(PROJECT_NAME) $(PROJECT_VERSION)$(RESET)"
+ @pip install .
+
+.PHONY: dev
+dev: ## Install the project in the current environment, with its dependencies, including the ones needed in a development environment
+ @echo "$(BOLD)Installing $(PROJECT_NAME) $(PROJECT_VERSION) in dev mode$(RESET)"
+ @pip install -e .[dev]
+ @$(MAKE) full-clean
+
+.PHONY: dev-upgrade
+dev-upgrade: ## Upgrade all default+dev dependencies defined in setup.cfg
+ @pip install --upgrade `python -c 'import setuptools; o = setuptools.config.read_configuration("setup.cfg")["options"]; print(" ".join(o["install_requires"] + o["extras_require"]["dev"]))'`
+ @pip install -e .
+ @$(MAKE) full-clean
+
+.PHONY: dist
+dist: ## Build the package
+ @echo "$(BOLD)Building package$(RESET)"
+ @python setup.py sdist bdist_wheel
+
+.PHONY: clean
+clean: ## Clean python build related directories and files
+ @echo "$(BOLD)Cleaning$(RESET)"
+ @rm -rf build dist $(PROJECT_NAME).egg-info
+
+.PHONY: full-clean
+full-clean: ## Like "clean" but will clean some other generated directories or files
+full-clean: clean
+ @echo "$(BOLD)Full cleaning$(RESET)"
+ find ./ -type d -name '__pycache__' -print0 | xargs -tr0 rm -r
README.rst¶
- Type
Added
- Stats
+152 -0
@@ -0,0 +1,152 @@
+=============================================
+IssHub : Your essential Git.Hub.Lab companion
+=============================================
+
+
+Welcome to the repository where `IssHub <https://isshub.io>`_ v2 is developed.
+
+--------
+Abstract
+--------
+
+IssHub is an "ISSues Hub", where you can manage your issues (and code requests, notifications...) from code hosting platforms like Github and Gitlab, in one place, with a common interface and advanced tools.
+
+This is the repository of the second version, that is developed in a totally different way that the previous one: progressive, clean and in the open.
+
+----------
+Motivation
+----------
+
+The first version was developed starting on a "Proof of concept" and evolved over several years without a clear vision on what was the goal, and no proper code architecture.
+
+When `Joachim Jablon <https://github.com/ewjoachim>`_ and I prepared our `talk fo the Djangocon Europe 2019 in Copenhagen, "Maintaining a Django codebase after 10k commits" <https://www.youtube.com/watch?v=_DIlE-yc9ZQ&t=724s>`_, I "saw the light" and wanted to do a little experiment around all we talked about.
+
+In the few months prior to the conference, as a planed sponsor, I worked a lot in IssHub to have it ready, bug-free (ahem) and mainly the biggest new feature since I started to work on this project in 2013: support for Gitlab in addition to Github.
+
+It was a real pain as I encountered all the pain points we tried to solve in our talk
+
+Third parties
+ Over 6 years, Django evolved a lot, and a lot of third parties were abandoned. Upgrading was very difficult. Proof: IssHub v1 is still on Python 2.
+
+Code architecture
+ The original proof of concept was to simply be able to organize issues with labels. So, as a POC, it was normal to follow Github on how to model things. But Gitlab, does things in a very different way and I had to make it fit the Github model.
+
+ So there was no clear separation (and even no separation at all) between the "domain", and all the rest of the application.
+
+ And finally the logic was everywhere: in the models, in the managers, in the views, in the templates.... Exactly what you want to avoid to maintain - and evolve - a big project.
+
+Tests
+ I won't speak about tests in IssHub v1: I gave up on many parts, because of the big bowl of spaghetti I had.
+
+So after our talk, instead of a little experiment about what we learnt in the process, I asked myself: why not starting up IssHub again, but this time doing it properly, and in the open, to force myself to do the things correctly.
+
+And it could also be a good way for others to see what I, as a 43 years old senior developer with half of my life as a paid developer, think is **a** (and not **the**) good way of developing a "big project"
+
+
+---------
+Rationale
+---------
+
+The main concepts that are used on this project:
+
+- coding in the open
+- developer friendly
+- future friendly
+- clear separation of concerns
+
+''''''''''''''''''
+Coding in the open
+''''''''''''''''''
+
+The main reason for the code of IssHub v1 to be "closed source" is because I'm not proud of it. It is really far from everything I try to transmit at work: quality is important, if not the most important.
+
+By doing this in the open, it will force me to do things well.
+
+It will also be for me a good resource to provide when looking for new freelancer missions.
+
+And, I hope, it can become a reference for everything I do elsewhere, from my own pet projects, to other "big projects" I may create in the future, or to simply pick ideas, code snippets, etc. when working for someone else.
+
+And finally, having it in the open allow other people to participate in many ways (reporting bugs is a good start)
+
+'''''''''''''''''''''''''''''
+Developer and future friendly
+'''''''''''''''''''''''''''''
+
+ “Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live”
+
+ -- John F. Woods
+
+aka: future you
+
+Nobody knows the future. A project started alone after work can become a big company later. Or it can just be you in a few years having to deal with "just a quick fix" made by past you. Or you simply want to have other hands working with you.
+
+In all these cases, you want your code to be clean. You don't want to fight to have great code readability. You don't want to have a fix break totally unrelated things.
+
+For this you want:
+
+- code linting
+- tests
+- documentation
+
+This will be one on the roots of this new rewrite of IssHub.
+
+''''''''''''''''''''''''''''
+Clear separation of concerns
+''''''''''''''''''''''''''''
+
+Having concerns separated allow better testing: each part can be unit tested, and the "glue" can be tested in integration mode.
+
+Updates are also easier because each part does one thing and does it well.
+
+The first thing we do is to do `Domain Driven Development <https://en.wikipedia.org/wiki/Domain-driven_design>`_: instead of mixing everything everywhere, domain logic will be apart from the rest. Considering Django as a third party app and not the center of the project, like it's very often the case.
+
+On the "domain", we'll delimit some "bounded context, for example the data we manage from the repositories, the local interaction between logged in users and these data, payment/subscriptions...
+
+So the domain will be a layer of our architecture. But it's not enough to make an application.
+
+We'll need a layer to handle the persistence, one to manage the synchronization between us and the remote sources (Github, Gitlab...), another to display things to the user.
+
+The domain is in the middle of all of these layers. It means that sync and front layers only handle data from the domain, not from the django ORM, which is only used as the persistence layer.
+
+We then won't be able to use some powerful features of Django, ie all the parts that link the orm to the rest of Django: no `ModelForm`, no `UpdateView`... but we can still use `Form` and `ModelFormMixin`, using our domain to pass data to Django, as "pure python objects", validate the data...
+
+It's a hard choice to make but for me, the separation of concerns, for a project of this size, is more important than the benefits of using Django as the ruler of everything.
+
+
+--------------
+Specifications
+--------------
+
+This part will evolve a lot during the development but there are still some things I know for sure.
+
+'''''
+Tools
+'''''
+
+All tools are incorporated in a `Makefile`, so it's easier to run commands. Tools listed below all have at least one `make` command to run them.
+
+Linting
+=======
+
+Documentation
+=============
+
+Testing
+=======
+
+Git
+===
+
+''''''
+Coding
+''''''
+
+Domain
+======
+
+Fetching
+========
+
+Frontend
+========
+
setup.cfg¶
- Type
Added
- Stats
+30 -0
@@ -0,0 +1,30 @@
+[metadata]
+name = isshub
+description = Yout essential Git.Hub.Lab companion
+long_description = file:README.rst
+version = 0
+author = Stéphane "Twidi" Angel
+author_email = s.angel@twidi.com
+license = MIT
+classifiers =
+ Development Status :: 2 - Pre-Alpha
+ License :: OSI Approved :: MIT License
+ Programming Language :: Python
+ Programming Language :: Python :: 3
+ Programming Language :: Python :: 3.7
+ Programming Language :: Python :: 3.8
+ Programming Language :: Python :: 3 :: Only
+keywords =
+ issues
+ github
+ gitlab
+url = https://github.com/Isshub-io/isshub
+requires-python = >=3.7
+
+[options]
+zip_safe = True
+packages = find:
+[options.extras_require]
+dev =
+ ipython
+ wheel