Technologies and Frameworks: General project features

[snordmann]

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:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. 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
• git-semver
• reno
• semantic-release

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]

I'd say GitReleases and ESLint.

[peoray]

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 🙂

[peoray]

Also, nothing was said about CI/CD?

[snordmann]

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]

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]

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]

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:

• https://eslint.org/docs/rules/
• https://medium.com/@uistephen/style-guides-for-linting-ecmascript-2015-eslint-common-google-airbnb-6c25fd3dff0

[rabbitwerks]

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

[ohmyshell]

@Sharpie360 me too.

[aronhoyer]

@mjmardini @Sharpie360 me too

[tigregalis]

@Sharpie360 @mjmardini @aronhoyer same