backgammon_ui_shared v1.22.1

UI Shared library

This library aims to be an unique repository when it comes to shared ui components. It can serve any private repository that shares common functionality, like using default button, cards, modal, etc.

The /lib folder

This folder is where reusable code across repositories is stored. There we will have some key directories like:

   lib
       | app-styles
       | components
       | hooks
       | icons
       | models
       | styles
       | services
       | contexts

Folders structure breakdown:

• app-styles - Styles than covers the entire application and can be used across applications/repositories, like the list of official colors.

• components - Reusable/Generic components that will be reused across the application. Each of these components will have its own folder and will contain unit tests and styles - with a self contained approach.

• hooks - Reusable React hooks that can be reused across application. For example, a hook that checks window sizes.

• icons - SVG icons empowered by React. Icons in here are exported as components with props, allowing us to change size, colors, rotation, etc.

• models - Typescript reusable interfaces and types. Examples are: List of reusable sizes, generic positions and options in general.

• styles - A list of style helpers developed in-company. To keep application consistent in it´s look and feel, reusable animations, effects and general app customizations goes under this folder.

• services - Generic/reusable code that is not directly related with the view or business logic. For example, a logger.

• context - to shared common app data across application.

Each of these folders will have an index.ts file exporting the whole group.

Versioning

This library uses semver to ensure it does not break on future releases. In order to have semver on the lib, we need to consider the following format for versioning: ... So, when consuming the lib, we should also append #.. version to the git URL, and ensure there is the same tag inside the lib repo.

Peer Dependencies

This library will consider that the host application has:

• React v. 16.18.6 or compatible
• React DOM v. 16.5.2 or compatible
• Material UI Core v. 4.11.3 or compatible
• Styled components v. 5.3.0 or compatible

So the libraries above are not packed into the final bundle.

Consuming

For using this library, follow the steps:

• Create an SSH key and add your public key to the repo. Having a passphrase is up to you, but remember that if you set a passphrase, you might be prompted often for it.

• have a config file(without extension) in your .ssh folder, containing this:

Host bitbucket.org
 AddKeysToAgent yes
 HostName bitbucket.org
 IdentifyFile <path to your private SSH key>
 User git

• Go to the project that will consume this library, and install it with the private repo ssh url:

npm i -S git+ssh://bitbucket.org/backgammoncompany/backgammon_ui_shared.git#<version_tag>

• Import and use a library module/component. For example:

import { BoxStyled } from 'backgammon_ui_shared';

• If you´ve noticed that the lib was updated, and you don't have the most up to date version, just reinstall it with the updated version:

npm i -S git+ssh://bitbucket.org/backgammoncompany/backgammon_ui_shared.git#<version_tag>

Ps1. While you are developing features, you don´t have to tag or use a tagged link. Just install the lib without the tag number, and you´ll get the most recent commit of the main branch.

Ps2. Installing wih https like this will work: npm i https://bitbucket.org/backgammoncompany/backgammon_ui_shared.git#<version_tag>, but this will be not accepted byt our CI environment and could be used only if you don´t have ssh configured yet.

Developing

Before developing components, we recommend the read of front-end docs of the backgammon_lobby repository. For developing something on this library, here are a couple of suggested steps:

• Download the repo (preferably where other backgammon projects are):

git clone git@bitbucket.org:backgammoncompany/backgammon_ui_shared.git

The link above is pointing to the code of the main branch, that is bg-v2.

• Create a new feature branch and install dependencies.

• Run npm start` so that webpack.config.dev.js can start a development server on port 3000, which is just a regular React application. The component can be used for both testing and as a demo app.

• Develop components inside the src/lib folder, respecting it´s structure: Every single component must be exported in it´s own index.ts file, and every group os elements(components, styles, etc) should have an index.ts exporting the whole group.

• If you want to see your changes on another repository, you´ll have to install the lib, telling npm to see your feature branch code:

npm i https://bitbucket.org/backgammoncompany/backgammon_ui_shared.git#<feature_name>

• Once you have finished with the development, open a PR targeting bg-v2 branch and ask for code review

Packing branch bg-v2 for production after a feature branch merge(Only for authorized devs)

Once a complete improvement is merged into bg-v2 branch, authorized developers should access bg-v2 and start packing the code for a new release. If you are releasing a new library version, do as follows:

• Make sure there are no merge conflicts on the branch and run npm run prettier:fix

• Think of a semantic versioning tag to apply to the "release commit". Go to package.json and update the version field with the new version to be released

• In order to prevent mismatch between package.json and package-lock.json, run npm install

• Run npm start to see if the project is being compiled successfully

• Update the change-log.md file with everything the new version is including, considering all features recently merged to bg-v2. Ask developers of each merged feature if necessary (or check tasks board), for listing what is new

• Run npm run build so webpack.config.prod.js will generate the dist folder with declarations and type definitions(*.d.ts), and also the library itself in index.js file

• Now your changes can be added to git staging. Commit with a message like "release commit", then push

• Check existing tags and/or check the latest annotated tag before creating your own tag. The commands are:

git tag -n - Lists all tags

git describe --abbrev=0 - List the most recent annotated tag

• Create and push an annotated tag (with a brief description), just like the example:

git tag -a -m "Include your tag message here" 1.0.0

git push origin --tags

Observations

1. By default, the last commit is going to be tagged, leaving us considering that this commit encloses a feature or update, and commits in-between are part of the new feature or update. We can also consider that tags will mark a stable version of our code that is ready to be released

2. Lightweight tags are just pointers to a specific commit. Annotated tags are stored as full objects in git. With annotated tags we can get much more information with commands like git show <tag_name> which shows tagger information. This is why annotated tags are always recommended

3. Tags in git are a flat list. Avoid adding too many tags(for every single commit for example), so this list does not get too long and difficult to manage in the future

4. If you need to tag past commits or manage tags in a particular way, refer to git-scm.com docs (check reference link on the bottom)

5. By default, the git push doesn’t transfer tags to remote repositories. We have to explicitly push a tag with git push origin <tag_name> or with git push origin --tags, that pushes any tags that are not yet published

6. If for some strong reason you need to delete a tag, you can delete it locally with git tag -d <tag_name> and than on remote(if needed) with git push origin <tag_name>. But remember, the best practice will be always creating a new tag

References

Semantic versioning

Getting started with webpack

Basic knowledge of tags

Why to use annotated tags