Technologies and Frameworks: General project features

snordmann commented 5 years ago

Hello together,

This issue is to hold a discussion about which frameworks to use. The scope of this issue is to decide on features all projects (currently backend and mobile app) should have.

Versioning and Release note management

We will be using Semantic Versioning for all projects.

Summary of Semantic Versioning:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,

MINOR version when you add functionality in a backwards-compatible manner, and

PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

As all npm packages and modules use this system, so will we. For more information on Semantic Versioning check out the specs.

There are several tools to automate and assist with a semver workflow. Al of the following tools can bump versions and create release notes more or less automated.

GitHub Releases

GitHub has this feature that allows you to tag specific commits to create a release. Whichever tool we decide on, all versions should be here too.

Using GitHub Releases without another tools consists of manually creating the tag and version string and after that uploading the build artifacts or other binary files.

Pro	Con
No external tools necessary	Completely manual
No changelog neccessary (although prefered)
Can be scripted (using POST requests)

git-semver

This works on either just a npm package.json file to get the current version and bump it, or it will look for a CHANGELOG.md file in the repository root. Using this tool one needs to manually run a script to bump the version and doing that decide, if this is just a patch, a minor or major release.

Pro	Con
easy to get into	need to release manually, not possible with CI
no need to keep a changelog (although prefered)

Reno

This is a release note management that is used in OpenStack. This framework can be dismissed easily, since it is far too complex for small projects and - far more important - it doe not work well with the Git Flow.

Pro	Con
-	does not work for our workflows

semantic-release

As last framework for release note and version management has the capability to create both without any manual configuration. If one merges to master this tool will run a job and determine which version to bump (path, micor, major) and the release notes that go with this version. It does this on tthe basis of all the commits. Using this tool we are constrained to use only commits according to the Angular Commit Message Conventions.

Pro	Con
can create releases automatically	Need to have a clean commit history

Last words about version management

Which ever tool we use, we will always publish to GitHub Releases, since many developers take this as the source of truth for the appication code and binaries. We could even add a changelog to every version on that platform.

So we need to think about how we will create a new version. Either we could do some things manual or completely automated. On the manual route it is possible to run a CI script when a git tag is created. Between manual and automated is the git-semver approach: Writing a CHANGELOG.md and running the script manually to bump a version. The completely automated way would be using semantic-release, but I don't like this very much because of the strict commit message guidelines. They will likely scare of first time contributors and add an overhead to the code review process.

Linting

As all projects will be written in ECMAScript ESLint will be used.

Configurations
- AirBnB
- Canonical
- ESLint
- prettier
- Standard
- others?
Things that ESLint can't find
- Spread syntax
- default parameter syntax
- spelling mistakes
- ???

Documentation

Should be publicly acessible
- Self-hosted
- Vuepress
- GitBook
- ???
- GitHub Pages
- GitHub Wiki
- ???
for backend
- swagger
for everything
- JsDoc

Feel free to comment on this issue and start a discussion on which framework / program to use. If I missed any app just leave a comment, I will add it as soon as possible.

Cheers, Semjon

thetornadotitan commented 5 years ago

I'd say GitReleases and ESLint.

peoray commented 5 years ago

Great options, gonna start from the top. As someone looking to learn and coming from a beginner's point of view:

I see CHANGELOG.md a lot in most projects on GitHub. I didn't even know it was for versioning purposes so I'd prefer it since it's more popular
ESLint seems to be the default choice here. Also, Airbnb and Prettier, Swagger and JSDocs
VuePress. I'm rooting for a Vue + Express application :slightly_smiling_face:

peoray commented 5 years ago

Also, nothing was said about CI/CD?

snordmann commented 5 years ago

CI/CD is something we can only think about once the final toolset is decided. Only then we can choose the right CI tool for us based on pricing, integration and required features. I listed some tools on #2 as it seemed appropriate to discuss the Continuous Delivery on the backend (aka. the thing that actually needs deployment).

Versioning-wise I'd use git-semver + GitReleases for our projects. It can be semi-automated with a working CI and reasonably easy to use. Only caveat would be that pull requests would need to document their changes in the CHANGELOG.md file what ultimately lead to some merge conflicts if not rebased. However writing a changelog is not a huge burden on the developer as a changelog captures only differences in a more or less high level perspective (check out https://keepachangelog.com for more information).

joshuaferr1s commented 5 years ago

In regards to ESLint it could be worth doing a poll of which features people want enabled or disabled and then have our own version with community choices by frequency of votes.

rabbitwerks commented 5 years ago

I like the Github Releases from first glance. I also have been using AirBnB for eslint for the last handful of projects as well. No experience using CI myself, yet. But ive heard good recommendations about CircleCI.

ohmyshell commented 5 years ago

Here's a list of all the ESLint Style Guides and some commonalities and differences to pick from.

Commonalities

2-Spaces
Quotes: Single
Brace Style for Control Blocks: Same Line
Prefer Const over var: Yes
No Trailing Spaces: True

Google JavaScript Style Guide

Tabs: 2-Spaces but 4-Spaces is not flagged
Semicolon: Required
Trailing Commas: Required
Template strings: No preference
Import Extensions: No preference
Object Curly Spacing: None
Array Bracket Spacing: None
Parentheses Around Arrow Function Arg: Required
JSDocs: Required (!)
Console statements: None
Underscored functions: Allowed
Space before function parentheses: None

AirBnB

Semicolon: Required
Trailing Commas: Required
Template strings: Prefer
Import Extensions: None
Space before function parentheses: None
Object Curly Spacing: Yes
Array Bracket Spacing: None
Underscored functions: None
Object Destructuring: Prefer
React Ordering: Opinionated
React Prop Validation: Required
Arrow Functions Return Assignment: No
Object Property Shorthand: Prefer

Standard

Semicolon: No
Trailing Commas: No
Template strings: No preference
Space before function parentheses: Required
Console Statements: None
Underscored functions: Allowed
Arrow Functions Return Assignment: Never
Import Extensions: No Preference
Object Curly Spacing: Consistent
React Ordering: Not opinionated
React Prop Validation: Not required

References:

rabbitwerks commented 5 years ago

Good work! A nice list of comparables. I am partial to the AirBnB standard over the google standard.

ohmyshell commented 5 years ago

@Sharpie360 me too.

aronhoyer commented 5 years ago

@mjmardini @Sharpie360 me too

tigregalis commented 5 years ago

@Sharpie360 @mjmardini @aronhoyer same

CodingGardenCommunity / app-wiki