text:
(eep-00)=

# EEP-00: Governance model & code of conduct

```{eval-rst}
+------------+------------------------------------------------------------------+
| Author     | `Maximilian Blesch <https://github.com/MaxBlesch>`_,             |
|            | `Janoś Gabler <https://github.com/janosg>`_,                     |
|            | `Hans-Martin von Gaudecker <https://github.com/hmgaudecker>`_,   |
|            | `Annica Gehlen <https://github.com/amageh>`_,                    |
|            | `Sebastian Gsell <https://github.com/segsell>`_,                 |
|            | `Tim Mensinger <https://github.com/timmens>_,                    |
|            | `Mariam Petrosyan <https://github.com/mpetrosian>`_,             |
|            | `Tobias Raabe <https://github.com/tobiasraabe>`_,                |
|            | `Klara Röhrl <https://github.com/roecla>`_                       |
+------------+------------------------------------------------------------------+
| Status     | Accepted                                                         |
+------------+------------------------------------------------------------------+
| Type       | Standards Track                                                  |
+------------+------------------------------------------------------------------+
| Created    | 2022-04-28                                                       |
+------------+------------------------------------------------------------------+
| Resolution |                                                                  |
+------------+------------------------------------------------------------------+
```

## Purpose

This document formalizes the estimagic code of conduct and governance model. In case of
changes, this document can be updated following the estimagic Enhancement Proposal
process detailed below.

```{include} ../../../CODE_OF_CONDUCT.md
```

## estimagic governance model

### Summary

The governance model strives to be lightweight and based on
[consensus](https://numpy.org/doc/stable/dev/governance/governance.html#consensus-based-decision-making-by-the-community)
of all interested parties. Most work happens in GitHub issues and pull requests (regular
decision process). Any interested party can voice their concerns or veto on proposed
changes. If this happens, the estimagic Enhancement Proposal (EEP) process can be used
to iterate over proposals until consesus is reached (controversial decision process). If
necessary, members of the steering council can moderate heated debates and help to
broker a consensus.

### Regular decision process

Most changes to estimagic are additions of new functionality or strict improvements of
existing functionality. Such changes can be discussed in GitHub issues and discussions
and implemented in pull requests. They do not require an estimagic Enhancement Proposal.

Before starting to work on estimagic, contributors should read
[how to contribute](how-to) and the [styleguide](styleguide). They can also reach out to
existing contributors if any help is needed or anything remains unclear. We are all
happy to help onboarding new contributors in any way necessary. For example, we have
given introductions to git and GitHub in the past to help people make a contribution to
estimagic.

Pull requests should be opened as soon as work is started. They should contain a good
description of the planned work such that any interested party can participate in the
discussion around the changes. If planned changes turn out to be controversial, their
design should be discussed in an estimagic Enhancement Proposal before the actual work
starts. When the work is finished, the author of a pull request can request a review. In
most cases, previous discussions will show who is a suitable reviewer. If in doubt, tag
[janosg](https://github.com/janosg). Pull requests can be merged if there is at least
one approving review.

Reviewers should be polite, welcoming and helpful to the author of the pull request who
might have spent many hours working on the changes. Authors of pull requests should keep
in mind that reviewers' time is valuable. Major points should be discussed publicly on
GitHub, but very critical feedback or small details can be moved to private discussions
— if the latter are necessary at all (see
[the bottom section of this blog post](https://rgommers.github.io/2019/06/the-cost-of-an-open-source-contribution/)
for an excellent discussion of the burden that review comments place on maintainers,
which might not always be obvious). Video calls can help if a discussion gets stuck. The
code of conduct applies to all interactions related to code reviews.

### estimagic Enhancement Proposals (EEPs) / Controversial decision process

Large changes to estimagic can be proposed in estimagic Enhancement Proposals, short
EEPs. They serve the purpose of summarising discussions that may happen in chats,
issues, pull requests, in person, or by any other means. Simple extensions (like adding
new optimizers) do not need to be discussed with such a formal process.

EEPs are written as markdown documents that become part of the documentation. Opening an
EEP means opening a pull request that adds the markdown document to the documentation.
It is not necessary to already have a working implementations for the planned changes,
even though it might be a good idea to have rough prototypes for solutions to the most
challenging parts.

If the author of an EEP feels that it is ready to be accepted they need to make a post
in the relevant [Zulip topic](https://ose.zulipchat.com) and a comment on the PR that
contains the following information:

1. Summary of all contentious aspects of the EEP and how they have been resolved
1. Every interested party has seven days to comment on the PR proposing the EEP, either
   with approval or objections. While only objections are relevant for the decision
   making process, approvals are a good way to signal interest in the planned change and
   recognize the work of the authors.
1. If there are no unresolved objections after seven days, the EEP will automatically be
   accepted and can be merged.

Note that the pull requests that actually implement the proposed enhancements still
require a standard review cycle.

### Steering Council

The estimagic Steering Council consists of five people who take responsibility for the
future development of estimagic and the estimagic community. Being a member of the
steering council comes with no special rights. The main roles of the steering council
are:

- Facilitate the growth of estimagic and the estimagic community by organizing community
  events, identifying funding opportunities and improving the experience of all
  community members.
- Develop a roadmap, break down large changes into smaller projects and find
  contributors to work on the implementation of these projects.
- Ensure that new contributors are onboarded and assisted and that pull requests are
  reviewed in a timely fashion.
- Step in as moderators when discussions get heated, help to achieve consensus on
  controversial topics and enforce the code of conduct.

The Steering Council is elected by the estimagic community during a community meeting.

Candidates need to be active community members and can be nominated by other community
members or themselves until the start of the election. Nominated candidates need to
accept the nomination before the start of the election.

If there are only five candidates, the Steering Council is elected by acclamation. Else,
every participant casts five votes. The 5 candidates with the most votes become elected.
Candidates can vote for themselves. Ties are resolved by a second round of voting where
each participant casts as many votes as there are positions left. Remaining ties are
resolved by randomization.

Current memebers of the estimagic Steering Council are:

- [Janoś Gabler](https://github.com/janosg)
- [Annica Gehlen](https://github.com/amageh)
- [Hans-Martin von Gaudecker](https://github.com/hmgaudecker)
- [Tim Mensinger](https://github.com/timmens)
- [Mariam Petrosyan](https://github.com/mpetrosian)

### Community meeting

Community meetings can be held to elect a steering council, make changes to the
governance model or code of conduct, or to make other decisions that affect the
community as a whole. Moreover, they serve to keep the community updated about the
development of estimagic and get feedback.

Community meetings need to be announced via our public channels (e.g. the
[zulip workspace](https://ose.zulipchat.com) or GitHub discussions) with sufficient time
until the meeting. The definition of sufficient time will increase with the size of the
community.

repository: OpenSourceEconomics/estimagic

gha_language: Python

repo_name: OpenSourceEconomics/estimagic


text:
# GIT Collaboration Exercise - With Mapping!

This is an exercise to help learn how to use Git in the context of mapping.

[GeoJSON](http://geojson.org/) is a flavour of JSON (Javascript Object Notation) that is used for denoting geography on the web.

## Setup

## Download

In your command line, type in `git clone https://github.com/brianbancroft/leaflet-git-exercise.git` and you'll be able load and edit the GeoJSON.

## Running

Bear with me. Generally, the best practice when running a web page is to do it on a virtual server.

This doesn't mean you have to purchase any special equipment, but there is some downloading to do. There are two really easy ways to pull this off:

- Download [Python](https://www.python.org/downloads/) and run `python -m SimpleHTTPServer 3000` in the command line while you're in the right directory, then  type in `localhost:3000` in your web browser address bar
  * (if you already have python, then you can skip the download)
### OR
- Download [NodeJS](https://nodejs.org/en/download/),
- Download [Node Package Manager (NPM)](https://docs.npmjs.com/getting-started/installing-node),
- In the command line, type in `npm install -g http-server`; then,
- Then type in `serve` in the command line (in the proper directory) and `localhost:8080` in the address bar

You don't have to reset either server when you've modified the files in the directory. Just refresh the browser!

license: MIT

repository: brianbancroft/leaflet-git-exercise

branch_name: refs/heads/master

extension: md

gha_language: JavaScript

gha_license_id: MIT

license_type: permissive

repo_name: brianbancroft/leaflet-git-exercise


text:
# ghaw

ghaw (GitHub at work) is useful CLI tool for professional GitHub users.

# Command

## `find-pull-requests`
Find pull-requests matching given filename.
Requires explicit merge commit with default message from GitHub.

```console
$ ghaw find-pull-requests HumbergerViewModel
https://github.com/toshi0383/hamburgerapp/pull/4119
https://github.com/toshi0383/hamburgerapp/pull/4089
https://github.com/toshi0383/hamburgerapp/pull/3824
https://github.com/toshi0383/hamburgerapp/pull/3533
https://github.com/toshi0383/hamburgerapp/pull/2912
```

## `ready-for-review`
Display pull-requests awaiting for your review.
One with `WIP` label is filtered.
This is the default command when you typed just `ghaw`.

```
$ ghaw
https://github.com/org/app/pull/4187 🔖v2.17.0 ✅0
https://github.com/org/app/pull/4256 🔖v2.16.0 ✅1 🤔
https://github.com/org/app/pull/4243 🔖v2.16.0 ✅2
https://github.com/org/app/pull/4239 🔖v2.16.0 ✅0 🤔
```

JSON output option (`-j`) is also supported in case you want to change the output.

## `job-done`
Display your comment count of each pull-requests which you've reviewed today.

# Install

## Mint
```
mint install toshi0383/ghaw
```

# Setup
Set `GITHUB_ACCESS_TOKEN` environment variable.

Repository information (owner/name) and GitHub username is automatically extracted from your environment. Use `-u` option if it's not correct or to use different GitHub user.
```
ghaw -u toshi0383 ready-for-review
```

# License
MIT

gha_language: Swift


text:
# # FinalGradeValue

## Properties

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**score_text** | **string** | A non-numerical or text representation of the score. | [optional]
**score_numeric** | **int** | A numerical record of the marks allotted to an individual in measuring their abilities. | [optional]

[[Back to Model list]](../../README.md#models) [[Back to API list]](../../README.md#endpoints) [[Back to README]](../../README.md)

branch_name: refs/heads/main

gha_language: PHP


text:
# MI-PAA Course
## Problémy a algoritmy
### CTU / ČVUT FIT

#### Task 1 - naive and aproximative Knapsack solver
We were implementing a naive and slightly improved aproximative solution using heuristic for the Knapsack problem. The main goal was to measure error of the approximative solution. The results contains graphs and the final report.

Solution can be compiled using `GNU make` on Linux and `Visual Studio` on Windows.

#### Task 2 - dynamic decomposition and FPTAS Knapsack solver
In the second part we took an advantage of previous one - another improvement was implementation of `branch and bounds` prunning. This approach effectively removes states which would never lead to a better solution that the current.

Another approach we implemented was `dynamic decomposition` and `fast polynomial-time approximation scheme` (`FPTAS`).

This version can be compiler only using the `GNU make`.

#### Task 3 - eomparison of methods
We took previously programmed solver on the Knapsack problem and let it crush a lot of different instances. The basic difference was that results depend on the instance properties.

Folder contains the final report as well as graphs and exact runtimes.

#### Task 4 - evolution algorithm Knapsack solver
The last algorithm trying to solve the Knapsack problem was evolutin algorithm. As this is random algorithm results may (and will) change over time.

The solution was created for the `Visual Studio`

#### Semestral work - evolution algorithm 3SAT solver
Our semestral work was focused on 3SAT problem. We took an advantage of previous experience with evolution programming. I was enough to copy solution of the 4th task and bend it. I had changed problem representation in the genom and added another parameter tuning features. My approach was to use parameter grid, when we iterate over each parameter's value until all parameter space is exhausted.

The final report describing my approach, overall quality and results is in the place.

Unfortunately this approach was not **fully appreciated** during the evaluation. **You have been warned!**

repository: holoubekm/MI-PAA

repo_name: holoubekm/MI-PAA


text:
# arc-jwt

Middleware that validates JsonWebTokens and sets `req.user`.

This module lets you authenticate HTTP requests using JWT tokens in your arc.codes
applications.  JWTs are typically used to protect API endpoints, and are
often issued using OpenID Connect.

## Usage

The JWT authentication middleware authenticates callers using a JWT.
If the token is valid, `req.user` will be set with the JSON object decoded
to be used by later middleware for authorization and access control.

For example,

```javascript
var jwt = require('arc-jwt');

arc.http(jwt({secret: 'shhhhhhared-secret'}),
  function(req, res) {
    if (!req.user.admin) return res.sendStatus(401);
    res.sendStatus(200);
  });
```

You can specify audience and/or issuer as well:

```javascript
jwt({ secret: 'shhhhhhared-secret',
  audience: 'http://myapi/protected',
  issuer: 'http://issuer' })
```

> If the JWT has an expiration (`exp`), it will be checked.

If you are using a base64 URL-encoded secret, pass a `Buffer` with `base64` encoding as the secret instead of a string:

```javascript
jwt({ secret: new Buffer('shhhhhhared-secret', 'base64') })
```

This module also support tokens signed with public/private key pairs. Instead of a secret, you can specify a Buffer with the public key

```javascript
var publicKey = fs.readFileSync('/path/to/public.pub');
jwt({ secret: publicKey });
```

By default, the decoded token is attached to `req.user` but can be configured with the `requestProperty` option.

```javascript
jwt({ secret: publicKey, requestProperty: 'auth' });
```

The token can also be attached to the `result` object with the `resultProperty` option. This option will override any `requestProperty`.

```javascript
jwt({ secret: publicKey, resultProperty: 'locals.user' });
```

Both `resultProperty` and `requestProperty` utilize [lodash.set](https://lodash.com/docs/4.17.2#set) and will accept nested property paths.

A custom function for extracting the token from a request can be specified with
the `getToken` option. This is useful if you need to pass the token through a
query parameter or a cookie. You can throw an error in this function and it will
be handled by `express-jwt`.

```javascript
arc.http(jwt({
  secret: 'hello world !',
  credentialsRequired: false,
  getToken: function fromHeaderOrQuerystring (req) {
    if (req.headers.authorization && req.headers.authorization.split(' ')[0] === 'Bearer') {
        return req.headers.authorization.split(' ')[1];
    } else if (req.query && req.query.token) {
      return req.query.token;
    }
    return null;
  }
}));
```

repository: amenglish/arc-jwt

repo_name: amenglish/arc-jwt


text:
---
layout: post
title:  "Git Flow"
date:   2016-08-02 10:21:42 -0400
categories: dev git
---

This tutorial does not require a deep understanding of git, however some
experience will be very helpful. If you're new at git you could learn most
important things [here](https://try.github.io/levels/1/challenges/1).
If you don't know what git is you might want to read this [small article](http://niclabs.cl/development/index/dev/niclabs/2016/07/13/version-control.html) first.

Most of the practices described here are based in [this](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow/) tutorial.

There is an interesting tool you can use for high level operations in git flow: [git-flow-cheatsheet](http://danielkummer.github.io/git-flow-cheatsheet/)

# Getting the repository

- ### Creating a new repository
   Go to *https://www.github.com/niclabs* and create a new repository.

- ### Clone an existent repository

   ```shell
   git clone https://www.github.com/niclabs/<repo-name>.git
   ```

# Working on the repository

- ### Choosing a branch to work on

  Now you are at the default branch of the repository, usually `master`. You can check the branch you are at with

    ```shell
    git branch
    ```

  When you clone a repository you will get all the branches from it, to see them type `git branch --all`. They will be prepended by `remotes/origin`, remotes indicates it is a remote branch and origin is the name of the remote repository.

- ### Developing a new feature / issue

  This is the case when you are adding a new feature to the project or trying to solve an open issue, this does not include high priority fixes (see [hotfix](#hotfix) for that). This is usually the case during a development.

  If your project is big enough it will have a development branch different from master, most of the time it will have an straight forward name as `develop`, `dev`, etc.. We'll call it `dev` but check with the repository maintainer for the particular name in the repository you're working at. If there isn't a development branch ask for creating one or use master. However, we strongly encourage you to use master as release branch.

  ```shell
  git checkout dev # Go to the development branch
  git pull # Pull if there are new changes
  git checkout -b new-feature # Create new branch
  git add new_feature.c # Add file with new feature
  git commit -m 'add new_feature.c with new_feature working' # Commit the changes
  git push -u origin new-feature # This will send the new branch to the remote
                                 # and track it (this mean in future changes you
                                 # can just say "push" and git will now where to
                                 # push).
  git add main.c # Add modified file
  git commit -m 'Add new_feature at main flow as default' # Commit the changes
  git push # Send the commit to the remote repository.
  ```

  Then just [create a pull request](#pullrequest)

## Hotfix

  This is the case when you have to fix a high priority bug as soon as possible.

  1. ### Pushing the change
     - #### Option 1
       Push a commit to the remote server directly in the default branch:

       ```shell
       git add lib.c # After lib.c is modified, add it to the staging area.
       git commit -m 'fix #23, syntax error at lib.c' # Commit the changes
       git push # Send the commit to the remote repository.
       ```

       Did you see `fix #23`? This indicates to [github](https://help.github.com/articles/closing-issues-via-commit-messages/) this commit is fixing the issue 23, so it should be closed.

     - #### Option 2

       Create a hotfix branch from the default branch.

       ```shell
       git checkout -b fix-issue23 # Creates and checkout (move) to a new branch named fix-issue23
       git add main.c # After is modified, add main.c to the staging area.
       git commit -m 'return 1 on file not found at main.c' # Commit the changes
       git add lib.c # After is modified, add lib.c to the staging area.
       git commit -m 'fix #23, syntax error at lib.c'
       git push -u origin fix-issue23 # This will send the new branch to the remote and track it.
       ```

       At this point you have the bug fixed at the `fix-issue23` branch, but you need to fix it at the default branch. You have to merge `fix-issue23` into the default branch. We have to ways to do this:

       1. Merge directly:

          ```shell
          git checkout master # Go to the default branch.
          git merge fix-issue23 # Merge fix-issue23
          git push # Push the merged master branch to the remote
          git branch -d fix-issue23 # Remove the branch locally
          git push origin --delete fix-issue23 # Remove the remote branch (you can also do this at github webpage).
          ```
       2. Start a Pull Request:

          This is the preferred way to add any change at the remote repository, we strongly encourage you tu use them, however is acceptable not to use a Pull Request when doing a hotfix.

          Pull requests let you tell others about changes you've pushed to a repository on GitHub. [Read More](https://help.github.com/articles/using-pull-requests/).

          How to create a Pull Request: [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/).

          Don't forget to assign someone to review the request, usually one of the project maintainers. If there isn't more people working in the project ask someone in the Lab to review it, prefer someone with knowledge of the language [check here](http://niclabs.cl/development/dev/2016/07/13/member-skills.html).

  2. ### Moving the hotfix to the development branch
     If you have a development branch you also want to apply the changes to it. How to do it is still an [open question](https://www.atlassian.com/git/articles/git-team-workflows-merge-or-rebase/), and there are mainly three options, we do prefer the first one:

     1. Rebase

        ```shell
        git checkout development # Move to  development branch
        git rebase master # Rebase development branch
        ```

     2. Merge

        ```shell
        git checkout development # Move to  development branch
        git merge master # Merge development branch with master
        ```

     3. Merge hotfix branch
        If you created a hotfix branch you could merge it directly to the development branch after you have merged it with the default branch.

        ```shell
        git checkout development # Move to  development branch
        git merge fix-issue23 # Merge development branch with the hotfix branch
        ```

repository: niclabs/development

branch_name: refs/heads/gh-pages

extension: markdown

gha_language: CSS

repo_name: niclabs/development


text:
# Storage Service

SaaS file storage API implementation using Python and Flask. Cloud Computing Class Final Project.

## Features

1. Authentication
2. Create file
3. Delete file
4. Open file content
5. List of files
6. Make directory
7. Delete directory
8. List of directories
9. Move file location
10. Move directory

## Requirements

1. Python 2.7.* or Python 3
2. Python packages:
```
pip install bcrypt pyjwt flask flask_restful gevent pickledb uuid
```

## Run Server
```
python main.py
```

## Files

1. AuthController.py: Authentication and registration controller
2. AuthRoutes.py: Contains Login and Register API
3. FileController.py: File operations controller
4. FileRoutes.py: Contains file operations API
5. main.py: Main execution file
6. UsersModel.py: Model interacting with 'users.db' file
7. requirements.txt: List of required python packages

## Sample Commands (APIs)

*tested in Windows 10

- Register
```
curl http://localhost:5000/register -X POST -d "{\"username\": \"admin\", \"password\": \"123456\"}"
```

- Login
```
curl http://localhost:5000/login -X POST -d "{\"username\": \"admin\", \"password\": \"123456\"}"
```

- Create file
```
curl http://localhost:5000/create -X POST -H "Authorization:<token>" -d "{\"file_path\": \"test1.txt\", \"file_content\": \"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\"}"
```

- Open file
```
curl http://localhost:5000/open -X POST -H "Authorization:<token>" -d "{\"file_path\": \"test1.txt\"}"
```

- Delete file
```
curl http://localhost:5000/delete -X POST -H "Authorization:<token>" -d "{\"file_path\": \"test1.txt\"}"
```

- List files
```
curl http://localhost:5000/lsfile -X POST -H "Authorization:<token>" -d "{\"folder_path\": \"\"}"
```

- Create directory
```
curl http://localhost:5000/mkdir -X POST -H "Authorization:<token>" -d "{\"folder_path\": \"new_folder_1\"}"
```

- Delete directory
```
curl http://localhost:5000/rmdir -X POST -H "Authorization:<token>" -d "{\"folder_path\": \"new_folder_1\"}"
```

- List directories
```
curl http://localhost:5000/lsdir -X POST -H "Authorization:<token>" -d "{\"folder_path\": \"\"}"
```

- Move files
```
curl http://localhost:5000/mvfile -X POST -H "Authorization:<token>" -d "{\"src\": \"test1.txt\", \"des\": \"new_folder_1\"}"
```

- Move dirs
```
curl http://localhost:5000/mvdir -X POST -H "Authorization:<token>" -d "{\"src\": \"new_folder_1\", \"des\": \"new_folder_2\"}"
```

- Check Storage Status
```
curl http://localhost:5000/status -H "Authorization:<token>"
```

## Docker - Getting Started
Make sure you have docker and docker-compose installed.

Build storageservice and reverseproxy image
```
docker build -t storage-service .
docker build -t reverseproxy reverseproxy
```

Run docker-compose
```
docker-compose up --scale storageservice=3 -d
```
This will make 3 storageservice containers and add reverse proxy as load balancer.
Reverse proxy is mapped to localhost:5000, so you can use above url example. Feel free to change it.

repository: lucassusanto/storage-service

repo_name: lucassusanto/storage-service


text:
# packer-dokuwiki

Uses Packer (https://www.packer.io/) to build a CentOS 7 based AMI with a configured Dokuwiki setup running on Apache. The goal is for this to stand up a clean Dokuwiki instance. After doing so the idea is that a git repository will be initialized and then the scripts provided will backup and restore your Dokuwiki instance, even on deletion. The VM can then be temporal, deleting and recreating it from the AMI whenever necessary.

This is intended for my personal use case: To stand up a temporal Dokuwiki instance at the start of my work day, use it throughout the day, and then back it up and destroy the VM at 5 o clock. The following morning, create an entirely new VM which will sync from the dokuwiki repo with no observable difference from the day prior. This keeps running costs cheap (generally I do not need a wiki during sleeping hours) and also prevents unnecessary data storage costs as well.

## Getting Started

This documentation will show you how to deploy this project using Packer. Some things like setting up the packer executable and automating the dokuwiki backup will be referenced but the step by step instructions for said tools are outside the scope of this article.

### Prerequisites

The installation steps assume you have the following:

```
Packer (https://www.packer.io/)
An AWS Account
AWS config and credentials setup in your .aws directory (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)
A blank git project to backup the wiki (I'm using GitLab for the free private repos, use your own as you'd like)
```

### Installing

A step by step walkthrough to deploy a Dokuwiki AMI

Edit the variables.json file with your values. Each value will be explained below.

```
{
  "instance_type": "t2.micro",
  "region": "us-east-2",
  "source_ami": "ami-9c0638f9",
  "admin_username": "admin",
  "admin_password_hash": "$1$YPnSdVNP$WttdnBXxmA.5lP4DrhqwN/",
  "wiki_title": "McCown Wiki",
  "git_domain": "gitlab.com",
  "git_initialized": "false",
  "git_project": "bmccown/dokuwiki-backup.git",
  "server_admin"<EMAIL_ADDRESS>  "server_name": "wiki.example.com",
  "server_alias": "wiki.example.com"
}
```
```
instance_type: Self explanatory. EC2 Instance Type
region: The region to deploy the AMI to
source_ami: The CentOS 7 AMI to use as a base image. You may have to go find this [here](https://aws.amazon.com/marketplace/pp/B00O7WM7QW)
admin_username: The username you'll use to login to dokuwiki
admin_password_hash: The password hash you'll use to login. This example here will be "Test123" minus the quotes. The easiest thing is to just keep this value, deploy dokuwiki, create a new user, delete the default admin user, and then from there on out the wiki will be deployed via your backed up git repo
wiki_title: Sets the wiki title in the Dokuwiki configuration files
git_domain: The domain where your git repository is hosted
git_initialized: If this is set to false the project will install dokuwiki, configure it, and back it up to your git repo. If it's set to true then dokuwiki will be restored from your git repo.
git_project: This will be joined with the git_domain value to make the connection string to set as the upstream for your git repo
server_admin: For dokuwiki config file purposes
server_name: For dokuwiki config file purposes
server_alias: For dokuwiki config file purposes
```

Next you'll need to ensure your Git repository is manageable via an SSH key. Edit the gitkey file and insert your own private key here.

Once that is done, deploy using:

```
packer build template.json -var-file=variables.json
```

After building the image for the first time, the wiki will be committed to your git repository. Edit your variables above to change git_initialized to true so that persistency can be maintained through your git repo.

## Contributing

Feel free to fork and create a pull request if you would like to contribute. This is a personal project but contributions are welcome.

repository: benmccown/packer-dokuwiki

repo_name: benmccown/packer-dokuwiki


text:
# Java Backend Coding Exercise

Please create a Spring Boot application that can be used to manage contacts using a RESTful API.
We ask you to meet the following requirements:
- Each contact has a full-name, date of birth and an address sub-entity.
- An address itself has two generic address fields, a city and a postal code.
- The application must be able to provide all existing contacts via a GET endpoint
- It is possible to filter contacts by zip-code so that not all but only some contacts are
returned
- It is possible to create a new contact (including address) using a POST endpoint
- Contacts are persisted to an in-memory database, which is started along with your
application
- Each contact has a unique identifier, which is generated by the database upon
storing a new contact
- The application performs logging every time a contact has been created

Also
- We need to be able to build and execute your application (please provide the code
e.g. as a github repo link)
- Your submission shows your coding style, how you name things and how you
structure your code (architecture)
- Please provide some sort of quality assurance. Feel free to use your preferred way of
doing that, suiting the scope of this test-project
- Describe your API in the README

Submission of the source code: Please create a Git repository on github.com for submission
and use this to develop the source code. After the development is finished, send us the link
to the Git repository via email. Please also make sure to provide the application itself and the
corresponding documentation for it in the form of a README file.
Please don't overstrain yourself, keep it simple so that you don't put in too many hours of
your time. It's not a university entrance exam :)
Good luck!

repository: frikit/contact-book

repo_name: frikit/contact-book


text:
---
title: "Kubernetes Tutorial part 2 of 3: How to Install and Deploy Applications
  at Scale on K8s "
date: 2021-03-31T15:14:49.442Z
author: Martijn Kieboom
authorimage: /img/Avatar1.svg
tags:
  - kubernetes
  - hpe-ezmeral-data-fabric
  - MapR
  - container
  - opensource
---
**Editor’s Note:** MapR products and solutions sold prior to the acquisition of such assets by Hewlett Packard Enterprise Company in 2019, may have older product names and model numbers that differ from current solutions. For information about current offerings, which are now part of HPE Ezmeral Data Fabric, please visit [https://www.hpe.com/us/en/software/data-fabric.html](https://www.hpe.com/us/en/software/data-fabric.html)

## Original Post Information:

```
"authorDisplayName": "Martijn Kieboom",
"publish": "2018-04-26T10:46:00.000",
"tags": "open-source-software"
```

---

_**Editor’s Note:**_ [Part 1 in this series](/blog/kubernetes-tutorial-how-to-install-and-deploy-applications-at-scale-on-k)

## Introduction

In my previous blog, I described the reasoning behind containers and how to manage them in large-scale production environments. This blog describes two ways to get started with Kubernetes:

For a small Kubernetes deployment, we will be using Minikube, a simple solution to run a single node environment locally on your environment using virtualization technology like VirtualBox or VMware.

After having some hands-on experience with Kubernetes using the Minikube environment, it is time to deploy an actual multi-node Kubernetes cluster. For that, we will be using a three node environment, running Red Hat/CentOS 7.x.

## Kubernetes Installation Using Minikube

If you don't have experience with Kubernetes, Minikube is a perfect way to take your first steps into the container management world. Minikube is an easy way to deploy a single node Kubernetes environment.

**Prerequisites**

Minikube leverages virtualization technology, like VirtualBox, VMware, Hyper-V, and others. So prior to running Minikube, make sure you have one of these virtualization technologies installed on your client. For a complete list of supported virtualization layers, visit the Minikube GitHub page at: [https://github.com/kubernetes/minikube](https://github.com/kubernetes/minikube)

With a virtualization technology installed on your machine, let's go ahead and install Minikube.

**Download Minikube**

Minikube comes in a precompiled, single executable file that you can simply download to your client:

```bash
# Install minikube on MacOS
curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/

# Install minikube on Linux
curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/

# Install minikube on Windows
# Download the executable file and save it as minikube.exe:
https://storage.googleapis.com/minikube/releases/latest/minikube-windows-amd64.exe

```

**Launch a Kubernetes Virtual Cluster**

With Minikube installed, it is time to launch our virtual single node Kubernetes cluster.

```bash
# Launch Kubernetes cluster
minikube start

# Alternatively, launch Kubernetes cluster with a specific Memory allocation
# default memory is 2048 MB
minikube start --memory 6144

```

That's all! No, really, it is.

Minikube will automatically download, import,and launch an image matching your virtualization technology. For that reason it does take a few minutes to complete. Notice that Minikube automatically imported a virtual machine into your virtualization environment.

There are many parameters you can configure as part of the 'start' command ('minikube start --help'), but as Minikube is aimed at ease of usage, the default values are a very solid standard to get started. One recommended parameter is to set the virtual machine's memory as configuration. It defaults to 2GB which might be on the small size if you want to try out a few containers on the Minikube cluster.

With the Kubernetes cluster running, we can use Minikube to connect to the VM and launch the Kubernetes Web Dashboard:

```bash
# Launch Kubernetes Dashboard
minikube dashboard

```

This will automatically launch your default browser and opens the Kubernetes dashboard. Whereas Kubernetes clusters will normally ask for a security token to login, Minikube is aimed at ease of use and therefore no login is required. Have a look around at the various Kubernetes menu options.

From here, you can now start deploying the MapR Volume Driver Plugin for Kubernetes.

If at any point in time you want to stop the Minikube cluster, it is as easy as you can imagine:

```bash
# Stop Kubernetes
minikube stop

```

The 'stop' command will gently shutdown your virtualized Kubernetes cluster, including all containers that you might have deployed on it. A simple 'minikube start' will relaunch the existing VM again, after which you can use 'minikube dashboard' to open the Kubernetes Dashboard.

Once you're done with the Minikube Kubernetes cluster, simply delete the VM:

```bash
# Delete the Kubernetes VM
minikube delete

```

## Kubernetes Installation on Red Hat/CentOS 7.x

Once you have experience with Kubernetes by using Minikube, it is time to deploy a multi-node Kubernetes cluster. This paragraph describes how to deploy a multi-node Kubernetes cluster on an environment running CentOS as the Operating System.

One final note before we start: do not openly connect this deployed cluster to the internet as securing the Kubernetes cluster is out of scope for this blog.

**Prerequisites**

The commands in this prerequisite chapter have to be executed on each of the Kubernetes cluster nodes individually.

If you're using AWS EC2 nodes, make sure to enable the 'extra’ repository:

```bash
# On AWS EC2 enable the 'extra' repository containing git, docker, etc.

yum-config-manager --enable rhui-REGION-rhel-server-extras
```

To get started, we need to disable SELinux as well as memory swapping on all nodes:

```bash
# Disable SELinux
setenforce 0
sed -i '/^SELINUX./ { s/enforcing/disabled/; }' /etc/selinux/config

# Disable swap
swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

```

Additionally, we also need to enable bridged networking for Kubernetes:

```bash
# Set iptables
cat < /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
EOF
sysctl --system

```

And, as the last step of the prerequisites, we need to install Docker to run containers:

```bash
# Install docker
yum install -y docker

# Launch Docker and enable it on system boot
systemctl start docker
systemctl enable docker

```

**Kubernetes Installation**

The following commands also have to be executed on each of the individual cluster nodes.

Add the Kubernetes repository, and install the Kubernetes tools—kubelet, kubeadm, and kubectl:

```bash
# Install kubernetes repo
cat < /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOF

# Install Kubernetes and start it
yum install -y kubelet kubeadm kubectl
systemctl start kubelet
systemctl enable kubelet

```

At this point, we have the Kubernetes packages installed on all cluster nodes. We can now start configuring Kubernetes. To do so, run the following commands on only one (1) single cluster node.

On the first node of the cluster, initialize the Kubernetes master by running kubeadm init. Please note that this task might take minutes to complete, as it will pull in all required containers.

```bash
# Initialize Kubernetes master
# Validate the ip-address of the node:
hostname --ip-address

# If the ip address in the above command is correct, run the following.
# Otherwise manually provide the correct address for apiserver-advertise-address
kubeadm init --pod-network-cidr=<IP_ADDRESS>/16 \
--apiserver-advertise-address=$(hostname --ip-address)

# The kubeadm command will take a few minutes and it will print a 'kubeadm join'
# command once completed. Make sure to capture and store this 'kubeadm join'
# command as it is required to add other nodes to the Kubernetes cluster
```

Once the cluster is initialized, we can copy the generated configuration file (admin.conf) to the home directory ($HOME/.kube/config) for easy cluster administration using the kubectl cli:

```bash
# Deploy kube config
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

```

To allow the pods and containers to communicate over the network with each other, a cluster network is required to set up. Flannel is one of the various cluster networking solutions that we will use in this blog. For more information on Kubernetes networking, visit: https://kubernetes.io/docs/concepts/cluster-administration/networking/

```bash
# Install Flanner for network
# Doc: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#44-joining-your-nodes
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/v0.9.1/Documentation/kube-flannel.yml
```

Per default,Kubernetes doesn't run pods on the master node as that could potentially result in a resource as well as security conflict. Pods might require such a large amount of system resources that the Kubernetes master might be negatively impacted. For single node clusters, however, (in case of testing, etc.), you can enforce pods to run on the master node as follows:

```bash
# Allow pods on master (not recommended for production clusters)
kubectl taint nodes --all node-role.kubernetes.io/master-
```

It will take a couple of minutes for all containers to start. Use the following command to validate that all pods are running prior to continuing:

```bash
# Validate all pods are running
kubectl get pods --all-namespaces
```

You can manage Kubernetes completely via the command line tool kubectl, but having a visual and graphical user interface to manage the cluster state can be very useful as well. To do so, let’s deploy the Kubernetes Dashboard:

```bash

# Deploy Dashboard web ui
# https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/
kubectl create -f https://raw.githubusercontent.com/kubernetes/dashboard/master/src/deploy/recommended/kubernetes-dashboard.yaml
```

As the Kubernetes dashboard is also running in a Docker container, we need to modify its networking to access the dashboard from the outside world:

```bash
# Edit the dashboard to be open to the world (for demos only!)
# Change type from 'ClusterIP' to 'NodePort'
kubectl -n kube-system edit service kubernetes-dashboard
```

Kubernetes user administration is out of scope for this blog post. Instead, we will be allowing the default kube-system user to become a cluster administrator user. Again: not for production clusters!

```bash
# Make default user part of cluster admin
# not for production clusters, for demos only!
kubectl create clusterrolebinding --user system:serviceaccount:kube-system:default kube-system-cluster-admin --clusterrole cluster-admin
```

To log on into the Kubernetes dashboard, a login token is required. To obtain the login ticket:

```bash
# Get the login token
kubectl describe serviceaccount default -n kube-system
kubectl describe secret default-token -n kube-system
```

Alternatively, it is possible to open the dashboard without login required (once again: not required for production systems). Simply click the 'skip' button in the Kubernetes dashboard login page after applying the following:

```bash
# Allow opening the k8 dashboard without login (not for production clusters, for demos only!)
cat < k8auth.yaml
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: kubernetes-dashboard
  labels:
    k8s-app: kubernetes-dashboard
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: kubernetes-dashboard
  namespace: kube-system
EOF
kubectl create -f k8auth.yaml
```

Pods on Kubernetes will, by default, open networking ports in the 30000+ range. To get the Kubernetes Dashboard port number, execute the following:

```bash
# Get the port that kubernetes dashboard runs on (should be a port in 30000+ range)
kubectl -n kube-system get service kubernetes-dashboard
```

Launch the Kubernetes dashboard in your favorite internet browser:

```bash
# Open browser and connect to the Kubernetes Dashboard
https://:
```

If you run into networking issues when connecting to the Dashboard, try using the Kubernetes proxy to connect to the Kubernetes internal networking:

```bash
# If unable to connect to Dashboard, try using the Kubernetes proxy:
kubectl proxy

# With proxy running, open the Dashboard using the following url:
http://<IP_ADDRESS>:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/
```

With the master node up and running, it is possible to add additional nodes to your Kubernetes cluster. To do so, use the 'kubeadm join …' command, as noted earlier in this blog. Please note, however, that the kubeadm command uses security tokens to authenticate itself with the master node. These tokens will expire after 24 hours, after which a new token has to be generated as explained below:

```bash
# Add additional nodes to the cluster (if required) using the earlier noted kubeadm join command
kubeadm join …

# On Master, show all nodes part of the cluster:
kubectl get nodes

# In case the token to join has expired, create a new token:
# On Master, list the existing tokens:
kubeadm token list

# On Master, if there are no valid tokens, create a new token and list it:
kubeadm token create
kubeadm token list

# Join additional nodes in the cluster with the newly created token, e.g.,:
kubeadm join <IP_ADDRESS>:6443 --discovery-token-unsafe-skip-ca-verification --token 5d4164.15b01d9af2e64824
```

That's it: you now have a multi-node Kubernetes environment running!

**Troubleshooting and Reset**

When running into issues, use the following command to print logging information:

```bash
# Troubleshooting
journalctl -xeu kubelet
```

To remove a node from the cluster:

```bash
# On master, remove a node from the cluster (hard)
kubectl get nodes
kubectl delete nodes

# On the removed node, reset and uninstall ubernetes installation
kubeadm reset
yum erase kube* -y
```

## MapR Volume Driver Plugin for Kubernetes

The MapR Volume Driver Plugin for Kubernetes allows running anyDocker container from Docker Hub on a Kubernetes cluster where MapR is the persistent data store for the container. Deployment of the MapR Volume Driver Plugin is very straightforward and will work both on the previously described Minikube and on the CentOS Kubernetes environments.

Make sure to check the latest documentation of the Volume Driver Plugin for any changes: [https://docs.datafabric.hpe.com/62/PersistentStorage/kdf_installation.html](https://docs.datafabric.hpe.com/62/PersistentStorage/kdf_installation.html).

The MapR Volume Driver Plugin (like any other Kubernetes configuration and deployment) consists of various so-called yaml files to configure and deploy pods and containers. The yaml files for the MapR Volume Driver Plugin can be found on the public [package.mapr.com](https://package.mapr.com/) repository:

```bash
# Locate and check the latest version of the MapR Volume Driver Plugin:
https://package.mapr.com/tools/KubernetesDataFabric/

# To download the version 1.0.0 files, for example:
wget https://package.mapr.com/tools/KubernetesDataFabric/v1.0.0/kdf-namespace.yaml
wget https://package.mapr.com/tools/KubernetesDataFabric/v1.0.0/kdf-rbac.yaml
wget https://package.mapr.com/tools/KubernetesDataFabric/v1.0.0/kdf-plugin-centos.yaml
wget https://package.mapr.com/tools/KubernetesDataFabric/v1.0.0/kdf-provisioner.yaml
```

With the yaml files downloaded, it is required to specify the ip address of the Kubernetes master in the Volume Driver Plugin yaml configuration:

```bash
# Configure the MapR Kubernetes storage plugin to point to the Kubernetes Master:
vi kdf-plugin-centos.yaml

- name : KUBERNETES_SERVICE_LOCATION
  value: "changeme!:6443"

# Set the KUBERNETES_SERVICE_LOCATION ip to match your Kubernetes master node
```

The final step is to deploy the Kubernetes configuration files to launch the MapR Volume Driver Plugin. We will start with creating the "mapr-system" namespace (kdf-namespace.yaml) to run the Volume Driver Plugin in. Additionally, we set the role-based access control (kdf-rbac.yaml) so that containers on Kubernetes can access the MapR Volume Driver Plugin. Finally, we will deploy the MapR Volume Driver Plugin.

Simply use the kubectl command line tool to load the yaml files into Kubernetes:

```bash
# Launch the various yaml files to deploy the MapR Volume Driver Plugin
kubectl create -f kdf-namespace.yaml
kubectl create -f kdf-rbac.yaml
kubectl create -f kdf-plugin-centos.yaml
kubectl create -f kdf-provisioner.yaml
```

That's it! Check your Kubernetes Dashboard to validate the deployment status by navigating to the overview of the 'mapr-system' namespace.

To remove the MapR Volume Driver Plugin from your Kubernetes cluster:

```bash
# Remove the MapR Volume Driver Plugin:
kubectl delete -f kdf-plugin-centos.yaml
kubectl delete -f kdf-provisioner.yaml
kubectl delete -f kdf-rbac.yaml
kubectl delete -f kdf-namespace.yaml
```

## Additional Resources:

*   [Part 1 in this series](/blog/kubernetes-tutorial-how-to-install-and-deploy-applications-at-scale-on-k)

*   [https://kubernetes.io/docs/setup/independent/install-kubeadm/](https://kubernetes.io/docs/setup/independent/install-kubeadm/)

*   [https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/)

*   [https://mapr.com/docs/home/PersistentStorage/kdf_overview.html](https://mapr.com/docs/home/PersistentStorage/kdf_overview.html)

repository: hpe-dev-incubator/hpe-dev-portal

gha_language: HTML

repo_name: hpe-dev-incubator/hpe-dev-portal


text:
---
title: "Visual design tips you can apply immediately"
date: "2017-07-04T11:51:00+00:00"
lastmod: "2019-10-04T07:24:49+00:00"
summary: "Add a little extra polish to any of your designs with these tips."
metadesc: "When designing there are things you can rely upon regardless of the situation. These are things which add extra polish, and are generally hidden to the untrained eye."
theme: "#fff7e0"
tags: ["Design"]
categories: ["Design"]
images: ["/static/images/blog/visual-design-tips-featured-image.png"]
large: "/static/images/blog/visual-design-tips-featured-image.png"
medium: "/static/images/blog/visual-design-tips-featured-image-medium.png"
ogImage: "/assets/og/cover.jpg"
status: "open"
id: 164
fileroot: "visual-design-tips-you-can-apply-immediately"
---

When designing there are techniques for applying colour, typography, spacing, you can rely upon regardless of the situation. These are things which add extra polish, and are generally hidden to the untrained eye.

## 1. Shadows respect their surroundings
One of the most common issues with shadows I see is they don't respect the background they are on.

<Image<EMAIL_ADDRESS>width={738} height={492} />

The ‘bad’ shadow uses 20% opacity black. The ‘good’ shadow uses #DBA758 at 60% opacity.

In the example, the ‘bad’ uses a black shadow. When a transparent black is placed on a coloured background, the overall colour appears muddier. Whereas if you take the background colour and make it darker and more saturated it will feel more intentional.

This is true of how real shadows behave, they're the absence of light. So while this is on a screen, it makes your design better if you remain true to this.

### How about blending modes?
Alternatively, you may find a blend mode more accurate. Using a black shadow with an overlay or soft light blending mode can be equally effective.

<Image<EMAIL_ADDRESS>width={738} height={492} />

Shadow ‘A’ is a softened shadow using an overlay blend mode. Shadow ‘B’ isn’t softened to demonstrate the colour.

In the example image, the shadows both use black with an overlay blending mode. This can be a great way to apply shadows which fit better. If you were to replicate this in CSS or without the need for a blending mode based shadow ‘B’ allows you to pick the colour and use it.

## 2.  It commonly happens with dark objects on a light background.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

It can take a bit of tweaking but you need two shadows, both of the same colour. You should keep your original shadow, but reduce the opacity and increase the Y axis slightly. **The idea is this shadow should be subtle**.

Next, duplicate the layer to add a second shadow. This shadow is 0 x axis, 1px y axis and 1px blur shadow. The opacity should be higher, around 60%. Essentially you’re creating a border for some additional contrast.

## 3. Gradients should feel harmonious
When you want a light to dark transition of colour in a gradient, usually you'll take your base colour and make it darker. That's fine, but sometimes it can feel off. Why? You may wonder.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

This is similar to the earlier shadow tip. A gradient applied to an object is adding depth. So similar rules apply, when darkening a colour, don’t only add black.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

In the image you can see a breakdown of the colours used. Comparing the examples the differences are more apparent. The good example uses a more saturated red.

### Use a different hue
Saturation doesn’t work as well for some colours, in those instances it can work to adjust the hue. Here are a couple of examples using hue adjustment only.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

By adjusting the colour on the hue of the colour, by around 10–20 degrees you perceive the colour as being darker.

## 4. Use hanging punctuation
It’s not supported in many apps (aside from InDesign) and CSS (yet). However, it’s an important consideration for improving your reading experience.

### Bulleted lists

  <Image<EMAIL_ADDRESS>width={738} height={492} />

When you indent your bullets at the first level you remove the left edge of the content. Your reader will have to adjust to the bullet points then again. It’s important to keep the left side consistent for the best reading experience.

### Quotes

  <Image<EMAIL_ADDRESS>width={738} height={492} />

The same applies to pull quotes, as seen in the image. If you’ve ever felt like your text feels off with quotes, this is why. It’s a subtle improvement.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

Of course your style may vary, and you may apply something more stylistic, as shown in the example for the design of this website.

## 5. Text always has an ideal line length
Having an ideal line length means content can be read easier. The eyes don’t have to work harder tracking from side to side.

Typically this is 55-75 characters, it depends on the typeface you use but this can be approximately 30em in CSS.

## 6. Balance titles & avoid widows/orphans
To avoid widows and orphans this means when you have a paragraph or title you avoid short lines of text. In the instance of titles it would be to avoid a single word. It can be difficult to control on a website, but being aware of it helps.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

It’s considered bad in terms of typography, because it looks like there is excess white space. Excess whitespace can interrupt the flow of reading and balance of a particular area of your design.

### How to fix or prevent?
When making a website there are a lot of variables to control this (eg: responsive). The best way I have found is to use ` ` on the areas you can control.

The title in the example would look like the following:

```
Illustrator quick tip: non destructive shape editing
```

## 7. Keep spacing consistent with using multiples
This is something I'm passionate about, using one multiple as a basis for all spacing. For example, using multiples of 8, this is a good number to use as it will divide/multiply and never hit a decimal placed number.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

There are a few good reasons you should be:

- Improves speed of designing
- Improves decision making
- Helps collaborating with developers
- Improves consistency and hierarchy
- Helps with maintaining a vertical rhythm

> Having your [Illustrator templates setup correctly](/blog/pixel-perfect-templates-in-illustrator) means this is a breeze to stick with.

## 8. Make sure icons and logos are pixel fitted
A subtle but important aspect of design is ensuring your design  assets remain sharp. Sometimes you may feel like something is off with an icon or logo, it most likely it looks ever so slightly blurry.

This is quite the topic in itself, but pixel fitting your icons and logos is an important skill to acquire. It’s essentially hinting them to make sure they appear sharp and retain their original clarity.

<Image<EMAIL_ADDRESS>width={738} height={492} />

Notebook icon from SS Standard

Take this notebook icon, the central rectangle is off the pixel grid. If you were to enable pixel preview cmd + Y and toggle it back and forth you would notice the fuzziness. *This is what I mean when making sure things are pixel fitted*.

You don’t see it in vector applications, but when you export and view it on screen normally you will see the difference.

### Making things pixel fitted

<Image<EMAIL_ADDRESS>width={738} height={492} />

Open the transform panel by going to Window > Transform

With the transform panel open, you use the direct selection tool  a to select the individual points. Referring to the transform panel you will see which points are off a whole pixel.

You can either add or subtract the pixels after the decimal place. The main thing is the numbers should be whole eg: 16px. Not 16.5px or 16.12325px, you get the point.

> Make Pixel Perfect is a feature which was added in Illustrator 2017 (Nov 2016 update). Make sure snap to pixel is on by going to View > Snap to Pixel and then select your object and go to Object > Make Pixel Perfect. It’s not fantastic, but it does do some heavier lifting.

## 9. Use a type scale
Like picking a consistent value to base spacing off; having a type scale is important too. A type scale means your font sizes are based upon a ratio.

I pick a scale that has the smaller font sizes you need and shows a clear difference with the larger sizes. As you need a variety at small sizes but more differentiation.

<Image<EMAIL_ADDRESS>width={738} height={492} />

Personally, I find a type scale of 1.125 to be ideal.

I would recommend using between 6–8 different type sizes. This should be more than enough for a website. Using more than this may make things feel inconsistent.

### [Modular Scale](http://www.modularscale.com/?18,12&px&1.333)
I recommend using this website to help determine your type scale. You can add multiple base values, this will give you a wider variety of smaller font sizes. It offers many sizes, but as mentioned I would select between 6–8.

## 10. Use the correct quotes
A simple one but using the correct quotes can make things look more elegant aside from being typographically correct. They vary in their look between typefaces, it could even be a factor in why you use that particular typeface.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

Straight quotes have very few if any uses outside of code. Some applications will automatically convert to them for you like Illustrator, Photoshop and some other text editors like iA Writer.

### Shortcuts
On a Mac the shortcuts are fairly straightforward, Windows and Linux require more effort. A good reference website for all shortcuts and entities is [Smart Quotes for Smart People](http://smartquotesforsmartpeople.com).

### Markdown
Markdown is a great way to write it’s simple to format text and one of the benefits of using markdown is the ability to enable quote conversion. If you write a lot in your CMS you may be able to enable it.

## 11. Optical alignment — aligning for your eyes
You’ve got a set of icons, you add a background colour in a circular shape, you align it and it looks off. The align tool isn’t broken surely?

It’s not broken, sometimes align tools don’t work in certain areas. The easiest way to get round this issue is to eyeball things, and that’s fine.

### The play icon
This particular icon is the most common example used when demonstrating optical alignment. As it’s really clear what the issue is.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

### Optical alignment comes in many forms
I’m only covering this topic briefly, but it applies to typography too. Being aware of when something is mathematically correct, but feels off from an optical view, will allow you to make the subtle tweaks needed.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

It’s a subtle, but noticeable difference, to the way things appear when aligned.

## 12. Make sure your nested corner radius account for the outer radius
When you have two rounded rectangles nested within each other you need the corner/border radius to feel consistent.

  <Image<EMAIL_ADDRESS>width={738} height={492} />

There is a fairly simple calculation for this, the `outer radius - the space between = inner radius`. In the example above this would be `40px - 28px = 12px`. There’s [a handy tool to help you calculate this](http://joshnh.com/tools/get-your-nested-border-radii-right.html).

## That’s it
Hopefully there are some tips you didn’t know here and they’re useful. I’d like to know have I missed any? Let me know on [twitter](https://twitter.com/irsteve)).

repository: stevemckinney/iamsteve

gha_language: SCSS

repo_name: stevemckinney/iamsteve


text:
SquareOne starter project
===========================

*****************************
by Ryan Baxter
Free to use - make it better!
*****************************

This project creates a GUI playground for coding in Visual Studio with CMAKE and Qt5.

It is useful for creating self-contained, deployable (zippable) apps. Build a project out of the codebase and thirdparty utilties as required.

Prerequisites
=============

1. CMake `(default: 3.3.1)`
2. Qt5 `(default: 5.11.1)`
3. MSVC `(default: Visual Studio 15 2017 Win64)`

Update software versions in ~\devops\scripts\config.bat

BUILD DIR
=========

*Run build.bat to create the build directory

    VS proj
        \build\SquareOne.sln

    Deployable app:
        \build\deploy
        \build\deploy\bin\Release\_Main.exe

    Generated Code:
        \build\generate\exports
        \build\generate\include
        \build\generate\library

SOURCE DIR
==========

codebase
--------

1. core    `Core libraries have no dependencies`
2. models  `Module Libraries may depend on Core Libraries`
3. systems `System Libraries may depend on Core and Module Libraries`

projects
--------

create project apps from the codebase

thirdparty
----------

support libraries (if included)

repository: rbax/SquareOne

repo_name: rbax/SquareOne


text:
---
title: Blog Week 10
layout: post
author: luke.amos
permalink: /blog-week-10/
source-id: 1HtLJqVNEOFS9f13IC5nf_lqxb4VzpJP0B_UTALwAoM0
published: true
---

An Introduction To Cyphers

Friday 25th November 2016

  Title:
    Blog Week 10

  Date:
    25/11/16

  Starting point:
    I was incredibly happy with the way my blog looked and was satisfied with the level of detail of my blog posts. I had little knowledge of ciphers although had an idea of how an Enigma Machine worked.

  Target for this lesson?
    To learn more about ciphers and cipher text and begin to use that knowledge to create my own codes. Also to learn more about the history of ciphers and learn about how different ciphers work.

    Did I reach my target?
    (add details to "Lesson Review"
    I did reach my target. I now have a good understanding of how different ciphers work and how they were and still are used through history. I also managed to encode my own message and test them on my classmates.

  Lesson Review

  How did I learn? What strategies were effective?

    My main strategy for learning this lesson was to listen intently to my I.T teacher as he explained the different aspects of cyphers. I was careful not to get distracted by my classmates, who were talking behind me. This was very annoying!

  What limited my learning? Which habits do I need to work on?

    The one thing that limited my learning was how I overthought things. I was constantly overthinking how Enigma worked and was getting very confused. I was also spending far too much time thinking about what message I would encode when I should have been actually encoding it.

  What will I change for next time? How will I improve my learning?

    I will try not to overthink things as it just overcomplicates what could be fairly easy to comprehend. Rather than spending time on thinking about different possibilities or scenarios, I should 'take it as it comes'. Also, I should focus more on the actual encoding of messages rather than trying to think of clever or funny messages to encode. This would allow me to learn more.


text:
### Introduction
A web browser (commonly referred to as a browser) is a software application for retrieving, presenting, and traversing information resources on the World Wide Web. An information resource is identified by a Uniform Resource Identifier (URI/URL) and may be a web page, image, video or other piece of content.Hyperlinks present in resources enable users easily to navigate their browsers to related resources.

Although browsers are primarily intended to use the World Wide Web, they can also be used to access information provided by web servers in private networks or files in file systems.

### Types of Browsers
There are five major browsers used today - Internet Explorer, Firefox, Safari, Chrome and Opera.
I will give examples from the open source browsers - Firefox,Chrome and Safari, which is partly open source.
According to the W3C browser statistics, currently(October 2009), the usage share of Firefox, Safari and Chrome together is nearly 60%.
So nowdays open source browsers are a substantial part of the browser business.

### Functionality

The browser main functionality is to present the web resource you choose, by requesting it from the server and displaying it on the browser window. The resource format is usually HTML but also PDF, image and more. The location of the resource is specified by the user using a URI (Uniform resource Identifier).

The way the browser interprets and displays HTML files is specified in the HTML and CSS specifications. These specifications are maintained by the W3C (World Wide Web Consortium) organization, which is the standards organization for the web.
The current version of HTML is 4 . Version 5 is in progress. The current CSS version is 2 and version 3 is in progress.

### Interface
Browsers' user interface have a lot in common with each other. Among the common user interface elements are

    Address bar for inserting the URI
    Back and forward buttons
    Bookmarking options
    A refresh and stop buttons for refreshing and stopping the loading of current document
    Home button that gets you to your home page

### Component
 Web browsers consist: Interface-
This includes the address bar, back/forward button, bookmarking menu etc. Every part of the browser display except the main window where you see the requested page.
 Layout engine-
Responsible for displaying the requested content. For example if the requested content is HTML, it is responsible for parsing the HTML and CSS and displaying the parsed content on the screen.
Rendering engine-responsible for displaying the requested content. For example if the requested content is HTML, it is responsible for parsing the HTML and CSS and displaying the parsed content on the screen.
JavaScript interpreter- Used to parse and execute the JavaScript code.
 UI backend-
used for drawing basic widgets like combo boxes and windows. It exposes a generic interface that is not platform specific. Underneath it uses the operating system user interface methods.
Networking component-used for network calls, like HTTP requests. It has platform independent interface and underneath implementations for each platform.
 Data persistence component-
This is a persistence layer. The browser needs to save all sorts of data on the hard disk, for examples, cookies. The new HTML specification (HTML5) defines 'web database' which is a complete (although light) database in the browser.
### References
[I'm an inline-style link](http://taligarsiel.com/Projects/howbrowserswork1.htm)
[I'm an inline-style link](http://arvindr21.github.io/howBrowserWorks/#/17)
[I'm an inline-style link](https://developers.google.com/web/updates/2012/04/Round-up-of-Web-Browser-Internals-Resources?hl=en)
[I'm an inline-style link](https://en.wikipedia.org/wiki/Web_browser)
[I'm an inline-style link](https://www.google.com)


text:
theories.topology
=================

* [basic](basic.lean) : open and closed sets, separation axioms, and generated topologies
* [limit](limit.lean) : a general theory of limits, based on filters
* [order_topology](order_topology.lean)
* [continuous](continuous.lean) : continuous functions

repository: soonhokong/lean

repo_name: soonhokong/lean


text:
pyrocms-cchat
=============

A simple chat module for PyroCMS (2.2.x). This uses conversejs and requires an XMPP server (using Prosody at the moment).

Here are the instructions on [running your own XMPP service with Prosody](http://richard.malibiran.com/2014/08/run-your-own-xmpp-service-with-prosody/). :)

Features
=================
- Create/Register a chat account (Administrators only)
- Chat to an XMPP server (using Prosody at the moment)
- HTTP Binding (user is logged-in to chat as long as he is logged-in to the webiste)

Installation
=================
1. Clone or download the source code
2. Extract it to the addons directory (you can also upload it using the upload module tool from the administrator's panel). Rename the pyrocms-cchat directory to cchat before installing. :)
3. Install it (just click the install button from the module pages of the administrator's panel)

TODO
=================
- Add settings for javascripts (or even css?) to fix the possible conflict with templates that uses the libraries that we are using. Examples are:
    - template_has_conversejs
    - template_has_jquery
- Create permissions on who can create a chat account for a user
- Automatically create a chat user upon registration
- Port to more chat providers (works best with a prosodyctl masking I made on node.js. will create a repo for it soon)
- Handle the registration failure properly
- Add authentication token for the registration routine
- Add tests

NOTE
=================
- I manually built conversejs to added the jquery no-conflict codes. If you are going to use the jquery included inside coversejs, use the original_converse.min.js file instead. (You can change it on the events.php file).
- I used spaces as tabs, tab-width 2

Thanks!
=================
- [PyroCMS](https://www.pyrocms.com)
- [ConverseJS](https://conversejs.org)
- [Candy Chat (for the XMPP prebinding codes/ideas)](https://github.com/candy-chat/xmpp-prebind-php)

repository: rmalibiran/pyrocms-cchat

repo_name: rmalibiran/pyrocms-cchat


text:
# orthocal-service

*NOTE*: Development on this repo has ceased. The project has been rewritten in python
and is available at [orthocal-python](https://github.com/brianglass/orthocal-python).

Orthocal-service is an Eastern Orthodox calendar service providing a RESTful
api describing commemorations, fasting, scripture readings and other
information for each day of the liturgical year.

A [Docker image](https://hub.docker.com/r/brianglass/orthocal-service/) is available.

A prototype is running at https://orthocal.info

The service is based on https://github.com/brianglass/orthocal.

repository: brianglass/orthocal-service

gha_language: Go

repo_name: brianglass/orthocal-service


text:
sencha-touch.jsx
===========================================

Synopsis
---------------

Sencha Touch API wrapper for JSX

Code Example
---------------

TBD

Installation
---------------

[jsx-init](https://npmjs.org/package/jsx-init) creates project to use this. Select `sencha-touch-app` project. `jsx-init` is a CUI project generating wizard:

```sh
$ npm install -g jsx-init
$ jsx-init
jsx-init: version 0.2.0
    By Yoshiki Shibukawa (https://github.com/shibukawa/jsx-init)
Project name [sandbox] >>> sandbox
npm Package name [sandbox] >>>
Short description [This is an awesome project to make everyone happy!] >>>
Version [0.1.0] >>>

1: jsx-lib          - includes: folder for library, unit test, sample app template.
2: node-app         - includes: command line tool source file, folder for library and unit test.
3: sencha-touch-app - includes: JSX source file, sencha-touch library and wrapper, html, css, web server setting to run on Chrome.
4: web-canvas-app   - includes: JSX source file, html, css to use Canvas API, web server setting to run on Chrome.

What type of project do you want to create? >>> 3

:
(omitting)
:

Enjoy JSX!
```

It creates setting files. `npm install` install needed tools including `sencha-touch.jsx` libraray.

Development
-------------

This is generated by [jsduck2jsx](https://npmjs.org/package/jsduck2jsx).

Author
---------

* shibukawa /<EMAIL_ADDRESS>
License
------------

MIT

Complete license is written in `LICENSE.md`.


text:
# gudmojo's list of nice things

My list of nice things which have something to do with software development.
These are my personal preferences, you may agree or disagree.

- The error-as-result mechanism works very nicely once you get used to it.
- Efficient usage of memory and cpu
- GoLand is a great IDE
- Recommended reading: Learning Go: An Idiomatic Approach to Real-World Go
  Programming by Jon Bodner

## Refactoring and legacy code

As new features are added to the codebase, it should be habitually refactored
so that it does not rot and become difficult to understand or modify.

Before adding a feature, refactor the code in a way that will make the feature
straight-forward to implement.

Code that is not covered by automated tests can't be confidently refactored.
Strong type systems also help a lot with that confidence.

One definition of legacy code is a codebase that is not covered by automated
tests.

## Infrastructure as code

Terraform is the default. If your infrastructure can be productively managed
using Terraform, do that.

If you're trying to provide self-service for an organization, requiring everyone
to make PRs to your Terraform can be a tall order. You might provide them with
published modules instead that they can instantiate in their own repo, but then
you have a dilemma about how much access that workspace will need. Will it need
edit access to shared fundamentals that you really don't want others to mess with?
When you get into that territory you might consider wrapping that access in code
that will control who is allowed to do exactly what and validates that the change
meets the standards and boundaries that you have established.

## GitOps

Have you ever been dealing with a production incident that could maybe be fixed by a
small change to your Kubernetes pod spec and now you have the choice between
making the change in the application repo and waiting 10 minutes for CI to run,
or you could kubectl edit the pod spec directly and be ready to revert just as quickly
if it fails. Wouldn't it be better to be able to make your change to the gitops repo
and have it applied without waiting for the application code to go through all the CI steps?
By having your k8s yaml manifests in a separate repo, "downstream" of the application,
you get the best of both worlds: Clear audit trail of *what* changed *when* by *who*,
and ability to act fast when you need to reconfigure something.

## Lean on your cloud provider

Cloud providers provide managed solutions that can reduce the work that goes
into maintaining and operating self-managed solutions. Don't do everything
yourself just to avoid "vendor lock-in".

There is also sometimes a third party that offers managed services. They can be
a good option, but make sure you are ok with depending on their service uptime
and access to support.

## Build your artifact once

The same artifact should flow through the release process from CI build to
production. Don't build for each deploy or build after QA gives go-ahead.

Otherwise you don't really know that the thing that passed testing is the same
as the thing you have in production. Also, an extra build is a waste of time
and resources.

## Team-owned services

A service should belong to a *single* team. They have the freedom to evolve it
as needed and the responsibility to keep the code in a good state. People outside
the team can collaborate with the team to get changes to the service.

## Developers are responsible for testing their changes

This creates a culture of taking quality into your own hands and creating fast
automated tests.

## Continuous deployment, controlled releases via feature flags

Empower developers to land code in production in a matter of minutes. Larger
features need to be communicated and timed, so hide them behind feature flags.

## Merge queue

Before merging PRs we want them to be 1) up to date with the main branch, and
2) passing CI with those updates. If the repo has many PRs about to be merged,
this can cause a game of whack-a-mole with rebasing and running CI, only to
find that there is another update on the main branch, so you need to rebase
again and wait for CI, wasting developers time and machine resources. This can
be solved by automation. The PRs are added to a merge queue and a bot takes care
of rebasing and merging one PR at a time.

GitHub.com and GitLab have built in support for merge queues.

## Integration testing

Deploy to a temporary environment and run some tests that will exercise the system
from the api to verify that the application actually works as a whole.

There are different ways to do this:

- Deploy on the CI runner using docker-compose. The disadvantage here is that your
docker-compose configuration has nothing in common with the way you deploy to production.
- Deploy to a fresh namespace in a kubernetes cluster. Benefit of this is that the
environment can be kept around if the build fails and then you can go and poke around
to see what caused the failure. Just create some mechanism that will delete the namespaces
after a certain time.

## Skaffold

 Skaffold (an open source project from Google) is a CLI for local development
 of a Kubernetes application, and can also be used in CI/CD so that both
 development and production deployments use the same tool.

## Hexagonal architecture (ports & adapters)

Keep a clear separation between your application's business logic and the code
that integrates to external actors such as the UI and the database.

Example: The business logic needs to look up currency exchange rates via an
external service. In that case the integration (constructing a json request and
sending it to a specific server) is written in a module unknown to the core
domain, but implementing an interface that the core domain specifies.

When this approach is used it's possible to achieve high flexibility in
switching to a different implementation of the same abstract service. It also
keeps the business logic clean and readable.

## Dependency Injection via constructor

I prefer to do my dependency injection manually. Each service type has a
constructor that receives all the dependencies that the service object needs.
The main function or entry point for the application is the place where I wire
up all the services manually by invoking constructors:

    dbConn = postgres.NewConnection(url)
    userRepo = postgres.NewUserRepo(dbConn)
    bookRepo = postgres.NewBookRepo(dbConn)
    server = server.New(userRepo, bookRepo)

The main function will be long and could be seen as a bit unvieldy, but in
my opinion it's nice to do it all there so you can see explicitly how everything
is wired and keep the rest of the application clean.

## Cassandra NoSQL database

- really fast
- instant strong consistency is possible using *quorum* writes and reads, even
  if a node is down.
- linear horizontal scaling up to millions of writes/sec
- masterless. no single point of failure
- no wait for failover when a node goes down
- near real time multi-datacenter replication is relatively easy
- SQL-like syntax, tables, columns

Caveats:

- It's total overkill for small projects and has higher ops overhead than simple managed datastores.
- No joins. Denormalize your data, perhaps using views or CQRS
- Automating backups can be a whole project

## Java

- I used to write a lot of Java in the past, but now I tend to lean towards Go.
- statically typed. I find it easier to read and modify code if I know the
  types of things.
- mature ecosystem of libraries and tools
- fast (on the server)
- IntelliJ is a great IDE

repository: gudmojo/nice-things

repo_name: gudmojo/nice-things


text:
# Change Log

All notable changes to this project will be documented in this file.
`grid-collection-view-controller` adheres to [Semantic Versioning](http://semver.org/).

---

## [1.0.2](https://github.com/Digipolitan/grid-collection-view-controller/releases/tag/v1.0.2)

update podspec

---

## [1.0.1](https://github.com/Digipolitan/grid-collection-view-controller/releases/tag/v1.0.1)

add brew update


text:
---
navigation_title: "From screen readers"
position: 2
---

# Hiding elements from screen readers using aria-hidden

**To hide an element from screen readers means: visually (on a computer screen) it is perceivable, but non-visual clients (for example screen readers) ignore it. This is done easily using ARIA, but you should never try this on focusable elements.**

Everything interesting about hiding elements from screen readers is written here: [Hiding elements from screen readers using aria-hidden](/examples/sensible-aria-usage/hidden).

gha_license_id: NOASSERTION


text:
A Control Framework for three.js
================================

The idea of this project is to provide a system
for writing controls in `three.js` so that:

- Each control does one specific thing, such as rotate, move, or scale
  an object or rotate or move the camera.
- Provide a class hierarchy to take care of most of the housekeeping
  of writing a control, so that, when you write one, you can just focus
  on the functionality.
- Provide a control manager that can assign one or more controls to
  handle mouse or touch events with different buttons pressed or
  gestures.

If a mouse or touchpad is used, the handler triggered can also depend
on which shift keys are pressed.

### Example: Duality of Platonic Solids ###

In the `examples` there is a simple application that illustrates
duality among platonic solids and demonstrates the variety of things
that can be done with the control framework.  You can see it in action
on doguleez.com or you can build it and serve it
yourself as described below.

The initial page of the describes the different things you can do with
the controls in it.

### Building the Control Framework ###

Note that this repository contains pre-built versions of the control
framework library and the duality example, so you don't have to build
unless you make changes to the code.  Further, the whole thing is
written with ES6 modules, so with minor tinkering you can just
use those directly and never build.

To build:

First, install `node.js`, if necessary.  Then:

    $ git clone <control framework url>
    $ cd control-framework
    $ npm install

Now do the following:

    $ npm run lib
	$ npm run duality

The first builds (concatenates) the framework library and the second does the same for the duality javascript, both using rollup.  It also builds concatenated ES6 modules for each.

Or you can do:

	$ npm run build-uglify
	$ npm run build-uglify-duality

which also compress the concatenated code and prepend the license.
But compressing is not really necessary because the code is quite
small.

### Serving the Duality Example ###

From the project root directory or from a directory
containing it, you can serve the planetarium though your favorite HTTP
server.  You will need to use an HTTP server rather than simply
reading `heliocentric.html` or `heliocentric-mobile.html` from file,
because browsers do not permit some WebGL operations for a page read
from file.

I use `http-server`, which you can install using `npm`.

    $ npm install http-server
    $ http-server -c-1

The "`-c-1`" is to prevent browser caching (because you are doing
development and always want the browser to use your latest code).

Now you should be able to access the duality example at

    http://localhost:8080/examples/index.html

This page gives instructions on how to use the controls.

repository: hooverdn/control-framework

repo_name: hooverdn/control-framework


text:
# Inpsyde Rules Configuration

## Inpsyde.CodeQuality.ElementNameMinimalLength

It is possible to configure the minimal length required to don't trigger any warning (by default 3).
That is possible via `minLength` property, e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.ElementNameMinimalLengthSniff">
    <properties>
        <property name="minLength" value="5" />
    </properties>
</rule>
```

It is also possible to configure the whitelist of allowed names with less than 3 (or whatever
the minimal length is configured to) characters.
By default the whitelisted names are:

 - `'i'`
 - `'id'`
 - `'is'`
 - `'to'`
 - `'up'`
 - `'ok'`
 - `'no'`
 - `'go'`
 - `'it'`
 - `'db'`

 but they can be configured via `allowedShortNames` config, e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.ElementNameMinimalLengthSniff">
    <properties>
        <property name="allowedShortNames" type="array" value="id,db,x,y" />
    </properties>
</rule>
```

-----

## Inpsyde.CodeQuality.FunctionBodyStart

This sniff enforces a blank line on top of function body when the function declaration spans
across multiple lines, e.g.:

```php
function foo(
    string $foo,
    string $bar
): bool {

    echo $foo . $bar;

    return true;
}
```

while blank line is forbidden for functions whose argument declaration is in one line and the
opened curly bracket is on next line, e.g.:

```php
function foo(string $foo, string $bar, string $baz): bool
{
    echo $foo . $bar;

    return true;
}
```

Blank line is also required if the opened curly bracket is on the same line (not PSR 1/2 compliant):

```php
function foo(string $foo, string $bar, string $baz): bool {

    echo $foo . $bar;

    return true;
}
```

A special case is when the first line of body contains a comment, in that case no blank line is required
before the comment, e.g.:

```php
function foo(
    string $foo,
    string $bar
): bool {
    // This is ok.
    echo $foo . $bar;

    return true;
}
```

-----

## Inpsyde.CodeQuality.FunctionLength

It is possible to configure the maximum allowed lines to don't trigger any warning (by default 50).
That is possible via `maxLength` property, e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.FunctionLengthSniff">
    <properties>
        <property name="maxLength" value="20" />
    </properties>
</rule>
```

By default, in the counting are excluded:
- white lines
- comments
- doc bloc _inside_ function block

It is possible to include any/all the lines of those kinds via 3 flags (by default all `true`):

- `ignoreBlankLines`
- `ignoreComments`
- `ignoreDocBlocks`

e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.FunctionLengthSniff">
    <properties>
        <property name="ignoreBlankLines" value="true" />
        <property name="ignoreDocBlocks" value="false" />
        <property name="ignoreComments" value="false" />
    </properties>
</rule>
```

-----

## Inpsyde.CodeQuality.LineLength

It is possible to configure the maximum allowed characters per line to don't trigger any warning
(by default 100).
That is possible via `lineLimit` property, e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.LineLengthSniff">
    <properties>
        <property name="lineLimit" value="120" />
    </properties>
</rule>
```

-----

## Inpsyde.CodeQuality.PropertyPerClassLimit

It is possible to configure the maximum allowed number of property per class to don't trigger any
warning (by default 10).
That is possible via `maxCount` property, e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.PropertyPerClassLimit">
    <properties>
        <property name="maxCount" value="120" />
    </properties>
</rule>
```

-----

## Inpsyde.CodeQuality.Psr4

`Inpsyde.CodeQuality.Psr4` rule needs some configuration to check namespace and
class file paths.
Without configuration the only thing the sniff does is to check that class name and file name match.
The needed configuration mimics the PSR-4 configuration in `composer.json`.
Assuming a `composer.json` like:

```json
{
  "autoload": {
    "psr-4": {
      "Inpsyde\\Foo\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Inpsyde\\Foo\\Tests\\": "tests/php/"
    }
  }
}
```
the rule configuration should be:

```xml
<rule ref="Inpsyde.CodeQuality.Psr4">
    <properties>
        <property name="psr4" type="array" value="Inpsyde\Foo=>src,Inpsyde\Foo\Tests=>tests/php" />
    </properties>
</rule>
```

Please note that when a PSR-4 configuration is given, *all* autoloadable entities (classes/interfaces/trait)
are checked to be compliant.
If there are entities in the sniffer target paths that are not PSR-4 compliant (e.g. loaded via classmap
or not autoloaded at all) those should be excluded via `exclude` property, e.g.:

```xml
<rule ref="Inpsyde.CodeQuality.Psr4">
    <properties>
        <property name="psr4" type="array" value="Inpsyde\SomePlugin=>src" />
        <property name="exclude" type="array" value="Inpsyde\ExcludeThis,Inpsyde\AndThis" />
    </properties>
</rule>
```

Note that anything that *starts with* any of the values in the `exclude` array will be excluded.

E.g. by excluding `Inpsyde\ExcludeThis` things like `Inpsyde\ExcludeThis\Foo` and
`Inpsyde\ExcludeThis\Bar\Baz` will be excluded as well.

To make sure what's excluded is a namespace, and not a class with same name, just use `\` as last
character.

-----

## Inpsyde.CodeQuality.ReturnTypeDeclaration

When there's no return type declared for a function, but it has a docbloc like:

```php
/**
 * return {$type}|null`
 */
```
and the function _actually_ contains both `null` and not-null return points **no** warning is shown.

However, if a minimum PHP version is set via [PHPCompatibility](https://github.com/wimg/PHPCompatibility)
`testVersion` config, and it is **7.1 or higher**, the warning **is** shown, because in PHP 7.1
there's the availability for nullable return types which should be used in that case.

Also note that the warning **is** shown in case:
 - the `@return` docbloc declares more than one not-null types, e.g. `@return Foo|Bar|null`
 - the `@return` docbloc types contains "mixed", e.g. `@return mixed|null`.

-----

## Inpsyde.CodeQuality.VariablesName

This sniff can be configured to enforce either `$camelCase` (default) or `$snake_case` variable names.

To change the check type, use `checkType` property, and set it to either: `"camelCase"` or `"snake_case"`
(any other value will be ignored and default will be applied).

```xml
<rule ref="Inpsyde.CodeQuality.VariablesName">
    <properties>
        <property name="checkType" value="snake_case" />
    </properties>
</rule>
```

By default, the sniff applies check to both local variables and class properties.

It is possible to ignore either local variables or class properties respectively via `ignoreLocalVars`
and `ignoreProperties` properties.

E.g.:

```xml
<rule ref="Inpsyde.CodeQuality.VariablesName">
    <properties>
        <property name="ignoreLocalVars" value="true" />
    </properties>
</rule>
```

No matter the check type used (`"camelCase"` or `"snake_case"`), PHP super globals variables and
WordPress global variables are always ignored.

It is possible to also ignore some other names via the `ignoredNames` property:

```xml
<rule ref="Inpsyde.CodeQuality.VariablesName">
    <properties>
        <property name="ignoredNames" type="array" value="ALLOWED,allowed_snake" />
    </properties>
</rule>
```

repository: fsw/php-coding-standards

repo_name: fsw/php-coding-standards