You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+25-5
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,15 @@
1
+
<!-- TOC -->
2
+
3
+
-[ProjectTemplate](#projecttemplate)
4
+
-[Documentation](#documentation)
5
+
-[Setup](#setup)
6
+
-[Using this product](#using-this-product)
7
+
-[Testing](#testing)
8
+
-[Sources and Links](#sources-and-links)
9
+
-[Contributors ✨](#contributors-)
10
+
11
+
<!-- /TOC -->
12
+
1
13
# ProjectTemplate
2
14
The project template for Code for Baltimore github projects. This project will help your project get started by giving you:
3
15
* A standard issues template
@@ -8,7 +20,7 @@ The project template for Code for Baltimore github projects. This project will
8
20
## Documentation
9
21
We've included a `docs` folder with a template [Tech Spec](/docs/Tech_Spec.md) and [Best Practices](/docs/Best_Practices.md) document, though using Github's Wiki capabilities is also a good idea. This will get you started with documenting your project. Other documents and relevant information that has no other place can live in the `docs` folder. Replace this paragraph with a brief breakdown of what you've included in your `docs` folder.
10
22
11
-
##Setup
23
+
# Setup
12
24
What does someone need to do to get started with your project? Do they need to:
13
25
* install software?
14
26
* run some commands?
@@ -22,13 +34,21 @@ How would someone use this product? Give a few examples here.
22
34
## Testing
23
35
What does someone need to do to test their work? Have you included a specific testing framework or guideline (hint: you should)? Any information about testing should be added here.
24
36
25
-
##Sources and Links
37
+
# Sources and Links
26
38
If referencing any third party service, code, etc, cite it here.
27
39
28
-
This template is in use on a number of other Code for Baltimore projects. For examples of use in various ways, please see the followings examples:
40
+
## Contributors ✨
41
+
42
+
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
43
+
44
+
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-[Merging and Pull Requests](#merging-and-pull-requests)
14
+
15
+
<!-- /TOC -->
16
+
1
17
# Best Practices
2
-
Code for Baltimore projects should be built with the intention of deploying on [Heroku](https://heroku.com). For details on Heroku Best Practices see their [developer documentation](https://devcenter.heroku.com/articles/node-best-practices).
18
+
Code for Baltimore projects should be built with the intention of deploying on [Heroku](https://heroku.com) or [Netlify](https://netlify.com). For details on Heroku Best Practices see their [developer documentation](https://devcenter.heroku.com/articles/node-best-practices).
3
19
4
20
## Project Management
5
-
6
21
We are using Github Issues to track outstanding issues and work for projects.
7
22
8
23
### Projects
9
-
10
24
Github Projects help organize our repositories by creating a Kanban board to track issues. These boards can be automatically generated by Github when creating the Project and should include a Todo, In Progress, Under Review, Reviewer Approved, and Done column. As issues are added to a Project they should be added to the board. A repo can have one or many Projects or boards at any given time.
11
25
12
26
### Issues and Milestones
13
-
14
27
When breaking down work it is important to add tasks to the Github project. For convenience various types of issues have templates built into this repo for easy issue entry. Before tasks are entered the project managers should agree on milestones based on the Project objectives. Issues should be tracked against Milestones so progress can be measured and planned for.
15
28
16
29
### Tagging Issues
17
-
18
30
When entering issues tagging can be used to further organize work or make work more visible to team members.
19
31
20
-
## Code Quality Standards
21
-
32
+
# Code Quality Standards
22
33
Regardless of Language:
23
34
24
35
- Default to `lowerCamelCase` naming convention
@@ -27,29 +38,22 @@ Regardless of Language:
27
38
- Provide meaningful code comments
28
39
- All commits must include a useful commit message
29
40
30
-
### Style Guides
31
-
41
+
## Style Guides
32
42
Consistent style guidelines for each language should be used. Where possible, openly published standards by authorities providing or using the language will be used.
33
43
34
44
Example: Google has openly published style guides for many languages in wide use on their open source projects, and these can be adopted for use in this project: [Google Language Specific Styleguides](https://google.github.io/styleguide/)
35
45
36
46
37
-
## Static Code Analysis
38
-
47
+
# Static Code Analysis
39
48
Static code analysis tools should be used when possible, to monitor and improve code quality. This may be integrated in the local development environment, automated repository commit checks, automated CI/CD pipelines, or other steps in the code development process.
40
49
41
-
### SonarQube scanning
42
-
Before committing or pushing any code changes those changes should be scanned with SonarQube. For convenience a `docker-compose` file has been included with this repository to facilitate local scans so that clean code can be checked and pushed before the deployment scans. See the [README](/sonarqube/README.md) in the sonarqube folder for more information.
43
-
44
-
## Git and Branching
45
-
50
+
# Git and Branching
46
51
All code work should be done in an isolated or feature branch off of the `master` branch. Before starting work on new code, developers should create their feature branch using a standard naming convention determined by the project.
47
52
48
-
###Branch Names
53
+
## Branch Names
49
54
Branch names should follow this patter: `<your github username>/issue-<github issue number>`. This will ensure there are no branch name conflicts, and anyone looking for your branch will know what it is called based on the issue addressed. For example if your username was letsGoOs, and you were working on issue 8, then your branch name would be `letsGoOs/issue-8`. If you wanted to make a new branch to continue your work on your issue then add a suffix with an incremented number. To continue the previous example if you wanted to make a second branch for your issue 8 work your second branch would be called `letsGoOs/issue-8-2`.
50
55
51
-
### Merging and Pull Requests
52
-
56
+
## Merging and Pull Requests
53
57
When work is complete, and after static code analysis has been performed, the developer should submit a pull request in Github. A pull request template has been provided, and developers should take care to fill out the form as completely as possible when submitting new pull requests omitting any sections that are deemed unnecessary for that particular submission. Pull requests should require at least 1 review from another verified team member before they are approved and merged into the `master` branch.
54
58
55
59
While not strictly required, it is recommended that pull requests are submitted early on in the development process with the intention of maintaining high visibility over the work while it is in progress.
The _Tech Spec_ is an important part of a project, but it's a part that's often overlooked or skipped. The intention of this document is to organize everyone's thoughts on the project into one simple, succinct document. It doesn't have to be super detailed but filling out this document will help keep everyone focused on the project goal.
0 commit comments