bitwarden-browser/CONTRIBUTING.md

How to Contribute

Contributions of all kinds are welcome!

Please visit our Community Forums for general community discussion and the development roadmap.

Here is how you can get involved:

• Request a new feature: Go to the Feature Requests category of the Community Forums. Please search existing feature requests before making a new one

• Write code for a new feature: Make a new post in the Github Contributions category of the Community Forums. Include a description of your proposed contribution, screeshots, and links to any relevant feature requests. This helps get feedback from the community and Bitwarden team members before you start writing code

• Report a bug or submit a bugfix: Use Github issues and pull requests

• Write documentation: Submit a pull request to the Bitwarden help repository

• Help other users: Go to the User-to-User Support category on the Community Forums

Contributor Agreement

Please sign the Contributor Agreement if you intend on contributing to any Github repository. Pull requests cannot be accepted and merged unless the author has signed the Contributor Agreement.

Pull Request Guidelines

• use npm run lint and fix any linting suggestions before submitting a pull request
• commit any pull requests against the master branch
• include a link to your Community Forums post

Setting up your Local Dev environment for jslib

In order to easily test, check and develop against local changes to jslib across each of the TypeScript/JavaScript clients it is recommended to use symlinks for the submodule so that you only have to make the change once and don't need to x-copy or wait for a commit+merge to checkout, pull and test against your other repos.

Prerequisites

1. git bash or other git command line

Clone Repos

In order for this to work well, you need to use a consistent relative directory structure. Repos should be cloned in the following way:

• ./<your project(s) directory>; we'll call this /dev ('cause why not)
  • jslib - git clone https://github.com/bitwarden/jslib.git (/dev/jslib)
  • web - git clone --recurse-submodules https://github.com/bitwarden/web.git (/dev/web)
  • desktop - git clone --recurse-submodules https://github.com/bitwarden/desktop.git (/dev/desktop)
  • browser - git clone --recurse-submodules https://github.com/bitwarden/browser.git (/dev/browser)
  • cli - git clone --recurse-submodules https://github.com/bitwarden/cli (/dev/cli)

You should notice web, desktop, browser and cli each reference jslib as a git submodule. If you've already cloned the repos but didn't use --recurse-submodules then you'll need to init those:

npm run sub:init

Configure Symlinks

Be aware that using git clone will make symlinks added to your repo be seen by git as plain text file paths, lets make sure this is set to true to prevent that. In the project root run, git config core.symlinks true.

For each project other than jslib, run the following:

For macOS/Linux: npm run symlink:mac

For Windows: npm run symlink:win

Updates and Cleanup

• Need to update parent repo that has jslib as a submodule to latest from actual jslib repo?
  • Create branch from master (git checkout -b update-jslib)
  • From new local branch: npm run sub:pull (git submodule foreach git pull origin master)
  • Follow Pull Request notes for commit/push instructions
  • Once merged, pull master, rebase your feature branch and then do npm run sub:update to catch your submodule up
• Discard changes made to a submodule
  • git submodule foreach git reset —hard

Merge Conflicts

At times when you need to perform a git merge master into your feature or local branch, and there are conflicting version references to the jslib repo from your other clients, you will not be able to use the traditional merge or stage functions you would normally use for a file.

To resolve you must use either git reset or update the index directly using git update-index. You can use (depending on whether you have symlink'd jslib) one of the following:

git reset master -- jslib
git reset master@{upstream} -- jslib
git reset HEAD -- jslib
git reset MERGE_HEAD -- jslib

Those should automatically stage the change and reset the jslib submodule back to where it needs to be (generally at the latest version from master).

The other option is to update the index directly using the plumbing command git update-index. To do that, you need to know that an object of type gitlink (i.e., directory entry in a parent repository that points to a submodule) is 0160000. You can figure it out from git ls-files -s or the following reference (see "1110 (gitlink)" under 4-bit object type): https://github.com/gitster/git/blob/master/Documentation/technical/index-format.txt

To use that approach, figure out the hash you want to set the submodule to, then run, e.g.:

git update-index --cacheinfo 0160000,533da4ea00703f4ad6d5518e1ce81d20261c40c0,jslib

see: https://stackoverflow.com/questions/26617838/how-to-resolve-git-submodule-conflict-if-submodule-is-not-initialized