Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lazy-cat-io/tools.project
A project management tool
https://github.com/lazy-cat-io/tools.project
clojure project-management project-management-tool
Last synced: 3 months ago
JSON representation
A project management tool
- Host: GitHub
- URL: https://github.com/lazy-cat-io/tools.project
- Owner: lazy-cat-io
- License: mit
- Created: 2022-04-03T19:10:10.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2022-04-11T22:28:34.000Z (almost 3 years ago)
- Last Synced: 2024-08-04T16:39:41.753Z (6 months ago)
- Topics: clojure, project-management, project-management-tool
- Language: Clojure
- Homepage:
- Size: 113 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.adoc
- Changelog: changelog.adoc
- License: license
Awesome Lists containing this project
README
image:https://img.shields.io/github/license/lazy-cat-io/tools.project[license,link=license]
image:https://img.shields.io/github/v/release/lazy-cat-io/tools.project.svg[https://github.com/lazy-cat-io/tools.project/releases]
image:https://github.com/lazy-cat-io/tools.project/actions/workflows/build.yml/badge.svg[https://github.com/lazy-cat-io/tools.project/actions/workflows/build.yml]
image:https://github.com/lazy-cat-io/tools.project/actions/workflows/deploy.yml/badge.svg[https://github.com/lazy-cat-io/tools.project/actions/workflows/deploy.yml]
image:https://img.shields.io/clojars/v/io.lazy-cat/tools.project.svg[clojars,link=https://clojars.org/io.lazy-cat/tools.project]
== tools.project
A project management tool.
**Status**: alpha
=== Features
- Unify a project manifest
- Collect dynamic metadata of builds at compile time (e.g. uberjar step) and use the metadata at runtime
- Transform a project manifest to https://github.com/seancorfield/build-clj[io.github.seancorfield/build-clj] format
- Manage project version
=== Getting started
==== Installation
Add the following dependency in your project:
.project.clj or build.boot
[source,clojure]
----
[io.lazy-cat/tools.project "0.1.82"]
----
.deps.edn or bb.edn
[source,clojure]
----
io.lazy-cat/tools.project {:mvn/version "0.1.82"}
----
==== Configuration
Add the project manifest to the project root directory.
.example-project
[source,bash]
----
.
├── .tools.project
│ └── config.edn <- project level configuration (variables, etc)
├── src
├── deps.edn
└── project.edn <- project manifest (any data)
----
.project.edn
[source,clojure]
----
;; juxt/aero and selmer libraries are supported
{:name io.lazy-cat/tools.project
:version "0.0.{{ git/commits-count }}{{ version/pre-release }}"
:description "A project management tool."
:license "MIT"
:author "Ilshat Sultanov "
:contributors [{:name "Ilshat Sultanov"
:email "[email protected]"
:url "https://github.com/just-sultanov"}]
:homepage "https://github.com/lazy-cat-io/tools.project#readme"
:repository {:url "https://github.com/lazy-cat-io/tools.project"}
:bugs {:url "https://github.com/lazy-cat-io/tools.project/issues"}
:keywords [:clojure :project-management :project-management-tool]
:build {:src-dirs ["src/main/clojure"]
:resource-dirs ["src/main/resources"]
:target "target"
:jar-file "target/tools.project.jar"
:scm {:url #ref [:repository :url]}}
:metadata {:build/created-at "{{ build/created-at }}"
:git/branch "{{ git/branch }}"
:git/sha "{{ git/sha }}"
:git/commit-message "{{ git/commit-message }}"
:git/author-email "{{ git/author-email }}"
:git/author-name "{{ git/author-name }}"
:git/author-timestamp "{{ git/author-timestamp }}"
:git/committer-email "{{ git/committer-email }}"
:git/committer-name "{{ git/committer-name }}"
:git/committer-timestamp "{{ git/committer-timestamp }}"}}
----
==== API
[source,clojure]
----
(ns example
(:require
[tools.project :as tp]))
;;;;
;; Configuration
;;;;
;; Stages of configuration building:
;; - reading the local configuration of the project (./.tools.project/config.edn)
;; - reading the global configuration from the user's home directory (~/.tools.project/config.edn)
;; - reading the default configuration (src/main/resources/io/lazy-cat/tools/project/config.edn)
;; example output
(tp/read-config)
=>
{
;; variables that can be used in project.edn in templates (uses Selmer under the hood)
:variables {:build/created-at "2022-04-09T22:44:47.299245Z"
:build/number "42"
:datetime/day "09"
:datetime/hour "22"
:datetime/minute "47"
:datetime/month "04"
:datetime/second "77"
:datetime/year "2022"
:git/author-email "[email protected]"
:git/author-name "Ilshat Sultanov"
:git/author-timestamp "2022-04-10T01:37:02+03:00"
:git/branch "master"
:git/commit-body nil
:git/commit-message "Add deploy step"
:git/commit-subject "Add deploy step"
:git/commits-count "64"
:git/committer-email "[email protected]"
:git/committer-name "Ilshat Sultanov"
:git/committer-timestamp "2022-04-10T01:37:02+03:00"
:git/sha "61770ee"
:git/tags nil
:git/url "[email protected]:lazy-cat-io/tools.project.git"
:version/pre-release ""}
;; build-clj configuration (:lib and :version parameters will be added automatically)
:build {:src-dirs ["src"]
:resource-dirs ["resources"]
:target "target"}}
;;;;
;; Project manifest
;;;;
(tp/read-project)
=>
{:name io.lazy-cat/tools.project
:version "0.0.64"
:description "A project management tool."
:license "MIT"
:author "Ilshat Sultanov "
:contributors [{:name "Ilshat Sultanov"
:email "[email protected]"
:url "https://github.com/just-sultanov"}]
:homepage "https://github.com/lazy-cat-io/tools.project#readme"
:repository {:url "https://github.com/lazy-cat-io/tools.project"}
:bugs {:url "https://github.com/lazy-cat-io/tools.project/issues"}
:keywords [:clojure :project-management :project-management-tool]
:build {:src-dirs ["src/main/clojure"]
:resource-dirs ["src/main/resources"]
:target "target"
:jar-file "target/tools.project.jar"
:scm {:url "https://github.com/lazy-cat-io/tools.project.git"}}
:metadata {:build/created-at "2022-04-09T22:44:47.299245Z"
:git/author-email "[email protected]"
:git/author-name "Ilshat Sultanov"
:git/author-timestamp "2022-04-10T01:37:02+03:00"
:git/branch "master"
:git/commit-message "Add deploy step"
:git/committer-email "[email protected]"
:git/committer-name "Ilshat Sultanov"
:git/committer-timestamp "2022-04-10T01:37:02+03:00"
:git/sha "61770ee"}}
;;;;
;; Project metadata
;;;;
;; Export a build metadata to resources directory using a project name (without build-clj configuration - :build key)
(tp/write-build-info (tp/read-project))
;; =>
;; Output: src/main/resources/io/lazy-cat/tools/project/build.edn
----
==== Customization
link:src/main/resources/io/lazy-cat/tools/project/config.edn[See default variables]
[source,clojure]
----
;; .tools.project/config.edn
{:variables
{:git/long-sha #git "rev-parse HEAD"}}
;; project.edn
{:version "v0.0.{{ git/long-sha }}"}
(tp/read-project)
=>
{...
:version "v0.0.61770ee7e611ce57840fdf45cb71e085d32134d5"
...}
----
===== CI/CD
If you need to use the variable `build/number` you should expose the environment variable `BUILD_NUMBER` or you can override `build/number` calculation.
[source,clojure]
----
;; default configuration
{:variables
{:build/number #or [#env BUILD_NUMBER "N/A"]}}
----
====== GitHub Actions
How to add `BUILD_NUMBER` on GitHub Actions:
[source,yaml]
----
- name: Setup environment variables
run: >-
echo 'BUILD_NUMBER=${{ github.run_number }}' >> $GITHUB_ENV;
----
=== Roadmap
- [ ] Stabilize the API
- [ ] Add validation using `malli` schemas
- [ ] Use `rewrite-edn` to preserve the manifest formatting style
- [ ] Add versioning support for `semver`, `git flow`
- [ ] Add usage examples with the babashka and Clojure CLI as tool `(-T)`
- [ ] Add support for `mono repositories`
=== License
link:license[Copyright © 2022 lazy-cat.io]