Skip to main content Skip to docs navigation
Check
View on GitHub

Contribute

Contribute to the development of git-deps-syncer using the documentation, build scripts and tests.

On this page

Tooling setup

  • bash is required for running/debugging the executable
  • Node.js is optional for managing the documentation site
Docs site is using npm scripts to build the documentation and compile source files. The package.json houses these scripts which used for various docs development actions.

Guidelines

  • PRs need to have a clear description of the problem they are solving
  • PRs should be small
  • Code without tests is not accepted, PRs must not reduce tests coverage
  • Contributions must not add additional dependencies
  • Before creating a PR, make sure your code is well formatted, abstractions are named properly and design is simple
  • In case your contribution can’t comply with any of the above please start a GitHub issue for discussion

How to Contribute?

  1. Fork this repository
  2. Create a PR on the forked repository
  3. Send a pull request to the upstream repository

Development Scripts

The makefile within this repository contains numerous tasks used for project development. Run make to see all the available scripts in your terminal.

Task Description
install_from_respository Install a local git-deps-syncer from this repository
uninstall Uninstall a local git-deps-syncer
release_version_create Create release tag in GitHub with version from resources/version.txt
release_version_delete Enter a tag to delete its attached release tag from GitHub
calculate_sha_by_commit_hash Enter a commit to get its SHA hash
calculate_sha_by_tag Enter a tag to get its SHA hash
serve_docs_site Run a local docs site
serve_docs_site_lan Run a local docs site (open for LAN)
test Run tests suite
fmt Format shell scripts using shfmt bash style (https://github.com/mvdan/sh)
Note that most of those development actions require write access to the repository.

Testing Locally

Running tests locally allows you to have short validation cycles instead of waiting for the PR status to complete.

How to run a test suite?

  1. Clone the git-deps-syncer repository
  2. Run make tests to run the tests suite

Documentation Scripts

The /docs-site/package.json includes numerous tasks for developing the documentation site. Run npm run to see all the available npm scripts in your terminal. Primary tasks include:

Task Description
npm run docs-build Cleans the Hugo destination directory for a fresh serve
npm run docs-serve Builds and runs the documentation locally
npm run docs-serve-lan Builds and runs the documentation locally, make it available on home network
(for testing views on mobile phones)
When running the docs site with LAN access, make sure to update the IP address of the docs-serve-lan script on the pacakge.json file.

Local documentation

Running our documentation locally requires the use of Hugo, which gets installed via the hugo-bin npm package. Hugo is a blazingly fast and quite extensible static site generator. Here’s how to get it started:

  • Run through the tooling setup above to install all dependencies
  • Navigate to /docs-site directory and run npm install to install local dependencies listed in package.json
  • From /docs-site directory, run npm run docs-serve in the command line
  • Open http://localhost:9001/git-deps-syncer in your browser

Learn more about using Hugo by reading its documentation.