Skip to content

Commit 3a9872e

Browse files
BagurpBagurp
committedJun 19, 2020
docs: Updates README, adds CONTRIBUTING.md
·
v0.8.17v0.6.0
1 parent 4e3ad76 commit 3a9872e

File tree

3 files changed

+156
-9
lines changed

3 files changed

+156
-9
lines changed
 

‎CONTRIBUTING.md

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
<!-- TOC -->
2+
3+
- [Contributing](#contributing)
4+
- [Branches](#branches)
5+
- [Commits](#commits)
6+
- [Use the Imperative](#use-the-imperative)
7+
- [Use the Body to Explain the Background and Reasoning, not the Implementation](#use-the-body-to-explain-the-background-and-reasoning-not-the-implementation)
8+
- [Subject Line Standard Terminology](#subject-line-standard-terminology)
9+
- [Documentation](#documentation)
10+
- [Code Review](#code-review)
11+
- [Deploy](#deploy)
12+
- [Task Workflow](#task-workflow)
13+
- [Definition of Done](#definition-of-done)
14+
15+
<!-- /TOC -->
16+
17+
# Contributing
18+
<a id="markdown-contributing" name="contributing"></a>
19+
*Detailed expectations for those contributing to this repository. A documented branching strategy is recommended. Trunk based development as default.*
20+
21+
This project uses a [git-flow based development](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) branching strategy.
22+
23+
[Trunk-based Development vs. Git Flow](https://www.toptal.com/software/trunk-based-development-git-flow)
24+
25+
## Branches
26+
<a id="markdown-branches" name="branches"></a>
27+
*Branch naming must be consistent and must be in [kebab-case](https://en.toolpage.org/tool/kebabcase). The following pattern is recommended -*
28+
29+
- feature-[Issue Number]/* - Feature additions
30+
- bugfix-[Issue Number]/* - Bug fixes
31+
- chore-[Issue Number]/* - Chore tasks
32+
- doc-[Issue Number]/* - Documentation tasks
33+
- release/[release-version] - Release versioning
34+
35+
For example,
36+
- feature-27/setup-postgresql
37+
- release/1.0
38+
39+
## Commits
40+
<a id="markdown-commits" name="commits"></a>
41+
*Consistent, verbose commits reduce the need for additional documentation. May be used for generating changelogs. Detailed instructions must be included either through a documented specification or custom documentation.*
42+
43+
This project uses the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) specification for commits.
44+
45+
https://github.com/talos-systems/conform
46+
47+
### Use the Imperative
48+
<a id="markdown-use-the-imperative" name="use-the-imperative"></a>
49+
*Consistent tense in commit messages.*
50+
51+
In keeping with the standard output of git itself, all commit subject lines must be written using the imperative:
52+
53+
Your commit subject line must be able to complete the sentence
54+
55+
> If applied, this commit will ...
56+
57+
If it doesn't, it's non-conformant. The body may use any style you want.
58+
59+
### Use the Body to Explain the Background and Reasoning, not the Implementation
60+
<a id="markdown-use-the-body-to-explain-the-background-and-reasoning-not-the-implementation" name="use-the-body-to-explain-the-background-and-reasoning-not-the-implementation"></a>
61+
62+
*Especially* if the diff is rather large or extremely clustered, you can save all fellow developers some time by explaining *why* you did *what*.
63+
64+
When possible the addition of screenshots, recorded gifs or other visual media is recommended.
65+
66+
### Subject Line Standard Terminology
67+
<a id="markdown-subject-line-standard-terminology" name="subject-line-standard-terminology"></a>
68+
69+
First Word | Meaning
70+
--- | --
71+
Add | Create a capability e.g. feature, test, dependency.
72+
Cut | Remove a capability e.g. feature, test, dependency.
73+
Fix | Fix an issue e.g. bug, typo, accident, misstatement.
74+
Bump | Increase the version of something e.g. dependency.
75+
Make | Change the build process, or tooling, or infra.
76+
Start | Begin doing something; e.g. create a feature flag.
77+
Stop | End doing something; e.g. remove a feature flag.
78+
Refactor | A code change that MUST be just a refactoring.
79+
Reformat | Refactor of formatting, e.g. omit whitespace.
80+
Optimize | Refactor of performance, e.g. speed up code.
81+
Document | Refactor of documentation, e.g. help files.
82+
83+
## Documentation
84+
<a id="markdown-documentation" name="documentation"></a>
85+
*Documentation must be treated as an integral aspect of development. This section describes expectations for documentation rigor and placement.*
86+
87+
In cases where the impact of a change is such that it is affects a fundamental component of the system, additional documentation is needed above what is presented in commit messages. This is by discretion, but it is advised to err on the side of more documentation than less.
88+
89+
In these cases, documentation should be added as markdown files within the project directory.
90+
91+
## Code Review
92+
<a id="markdown-code-review" name="code-review"></a>
93+
*Expectations for conducting code reviews, the merger of code and subesquent tasks*
94+
95+
Pull requests require a minimum of one reviewer to accept changes prior to merge. It is the responsibility of the person submitting the pull request to schedule a code review.
96+
97+
[Google Engineering - Code Review Developer Guide](https://google.github.io/eng-practices/review/)
98+
99+
## Deploy
100+
<a id="markdown-deploy" name="deploy"></a>
101+
*Deployment steps from the perspective of an engineer required to deploy to all of the available evironments.*
102+
103+
Once a pull request is merged the change will be automatically deployed to the appropriate environment.
104+
105+
# Task Workflow
106+
<a id="markdown-task-workflow" name="task-workflow"></a>
107+
*Description of how tasks are tracked through project management software and expectations of different roles.*
108+
109+
![Task Workflow Diagram](task%20workflow.png)
110+
111+
# Definition of Done
112+
<a id="markdown-definition-of-done" name="definition-of-done"></a>
113+
A task is complete when
114+
- All acceptance criteria have been met
115+
- Implementation has been code reviewed
116+
- All automated tests pass (e.g: Unit, end-to-end testing)
117+
- All manual tests pass (e.g: Functional, user interface testing)
118+
- Necessary documentation is reviewed
119+
- Implementation is deployed to the appropriate environment

‎README.md

+37-9
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,34 @@
1-
# Overview
2-
This repository contains a micronaut application for uploading files and tracking skill set of team members. This application will also be used for PDL checkins and auto generated resumes from the skill set.
1+
<!-- TOC -->
32

4-
# Getting Started
5-
To build this module, execute : `./gradlew assembleServerAndClient`. Please run this command twice.
6-
Once the build is successful then execute: `./gradlew run` and open the browser to run the application at `http://localhost:8080`.
7-
# Google Drive Upload
8-
Simple uploader application written in [Micronaut](https://micronaut.io) and targeted at GCP for uploading files to a limited access Google Drive folder.
3+
- [Check-ins](#check-ins)
4+
- [Project Links](#project-links)
5+
- [Setup](#setup)
6+
- [directory.json](#directory-json)
7+
- [credentials.json](#credentials-json)
8+
- [Running the application](#running-the-application)
9+
- [Contributing](#contributing)
910

10-
## Configuration
11+
<!-- /TOC -->
12+
13+
# Check-ins
14+
<a id="markdown-check-ins" name="check-ins"></a>
15+
This web application is written in [Micronaut](https://micronaut.io) for uploading files and tracking skill set of team members. This application will also be used for PDL checkins and to auto-generate resumes from the skill set.
16+
17+
# Project Links
18+
<a id="markdown-project-links" name="project-links"></a>
19+
**Project Document:** \*TBA\*
20+
21+
**Project Board:** [Board](https://github.com/oci-labs/check-ins/projects/1)
22+
23+
**Environments:** \*TBA\*
24+
25+
# Setup
26+
<a id="markdown-setup" name="setup"></a>
1127
There are two files required to run the application successfully. Both of which must be created and placed in
1228
`src/main/resources/secrets`
1329

1430
### directory.json
31+
<a id="markdown-directory-json" name="directory-json"></a>
1532
This is a simple JSON file containing the identifier for the Google Drive folder into which the uploaded files are to be deposited.
1633

1734
```json
@@ -21,6 +38,17 @@ This is a simple JSON file containing the identifier for the Google Drive folder
2138
```
2239

2340
### credentials.json
41+
<a id="markdown-credentials-json" name="credentials-json"></a>
2442
This JSON file should create the generated credentials for a service account that has access to write to the identified Google Drive folder. Information on configuring GCP service account credentials can be [found here](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).
2543

26-
Note: Be sure that the target Google Drive folder has edit access granted to the service account.
44+
Note: Be sure that the target Google Drive folder has edit access granted to the service account.
45+
46+
### Running the application
47+
<a id="markdown-running-the-application" name="running-the-application"></a>
48+
To build this module, execute the following command twice : `./gradlew assembleServerAndClient`
49+
Once the build is successful, execute: `./gradlew run`.
50+
Open the browser to run the application at `http://localhost:8080`.
51+
52+
# Contributing
53+
<a id="markdown-contributing" name="contributing"></a>
54+
[Contributing](./CONTRIBUTING.md)

‎task workflow.png

61.5 KB
Loading

0 commit comments

Comments
 (0)
Please sign in to comment.