Skip to content

Commit e6bc775

Browse files
ibarra-michelleibarra-michelle
committed
Added README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT md files
1 parent a18af4d commit e6bc775

File tree

4 files changed

+271
-0
lines changed

4 files changed

+271
-0
lines changed

‎CODE_OF_CONDUCT.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# US-EPA-CAMD Code of Conduct
2+
## Introduction
3+
We are committed to building a safe, friendly, and harassment-free culture for everyone. We pledge to interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
4+
5+
## Scope
6+
This Code of Conduct applies to the [USEPA](https://github.com/USEPA) GitHub organization, its communications, events, and anyone participating in the US-EPA-CAMD GitHub community. Your use of our repositories means you accept and agree to abide by this Code of Conduct, and the [EPA Comment Policy,](https://www.epa.gov/web-policies-and-procedures/epa-comment-policy/) which will be periodically revised.
7+
8+
## Expectations of Visitors and Contributors
9+
We expect all visitors and contributors to the US-EPA-CAMD GitHub organization and its repositories to have a safe and engaging experience that is beneficial to our community. Members of our community have a diverse set of experiences and skillsets. As you engage our community, please ensure you are:
10+
- Considerate: As an open source community, what you do will affect others. Ensure what you do is in the best interest of the project, and community at large.
11+
- Collaborative: The essence of open source is collaborative in nature. Be respectful of differing opinions and viewpoints.
12+
- Patient: Remember that open source is a culture change in government and while this repository is a testament to that change, change is occurring thanks to many in this community. Be patient if your question or issue is not answered right away.
13+
- Be mindful: Be aware of your actions, and others' actions. Treat people with empathy, dignity, and respect - the way you want to be treated.
14+
- Use clear communication: We don’t all speak the same language. Further, written or typed words may lack the tone or body language necessary to interpret intent or meaning. If your words could have more than one meaning, take time to be clear with your words and remember to be kind.
15+
16+
## Unacceptable Behavior
17+
Users have a reasonable expectation to engage in our community free from harassment. Harassment can include but is not limited to offensive verbal comments related to gender, age, sexual orientation, disability, physical appearance, race, religion, deliberate intimidation, disruption of talks or events.
18+
Anything that is unlawful, objectionable, offensive, abusive, threatening, defamatory, obscene, hateful, inflammatory, profane, racially, sexually or religiously offensive is not permitted.
19+
20+
## Enforcement
21+
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned to this Code of Conduct.
22+
23+
Unacceptable behavior from any community member, including those with decision-making authority, will not be tolerated. Anyone asked to cease unacceptable behavior is expected to comply immediately. If a community member engages in unacceptable behavior, the US-EPA-CAMD GitHub organization will take any action it deems appropriate, up to and including a temporary ban or permanent expulsion from the community without warning. This can include removal from email lists, team meetings, and repositories.
24+
25+
## Attribution
26+
This Code of Conduct is adapted from the following sources:
27+
- [Contributor Covenant](https://www.contributor-covenant.org/)
28+
- [Technology Transformation Services (TTS) Code of Conduct](https://18f.gsa.gov/code-of-conduct/)
29+
- [Consumer Financial Protection Bureau (CFPB) Code of Conduct](https://github.com/cfpb/consumerfinance.gov/blob/main/CODE_OF_CONDUCT.md)

‎CONTRIBUTING.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
## Welcome!
2+
3+
We’re so glad you’re thinking about contributing to an EPA open source project!
4+
5+
Please be aware that this repository is currently undergoing testing, so it is likely we will not immediately address your issue or pull request as your idea may already be in our product roadmap.
6+
7+
We encourage you to read this project’s CONTRIBUTING policy (you are here), its
8+
[LICENSE](https://github.com/usepa/code-json-generator/blob/main/LICENSE), and its [README](https://github.com/usepa/code-json-generator/blob/README.md).
9+
10+
All contributions to this project will be released under the MIT dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.
11+
12+
If you have any questions or want to read more, check out the [EPA Open Source Project Repo](https://github.com/USEPA/open-source-projects) and [EPA's Open Source Software Guide](https://www.epa.gov/developers/code).

‎LICENSE.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#MIT License
2+
3+
Copyright (c) 2020 U.S. Federal Government (in countries where recognized)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+209
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
2+
Inventory
3+
=========
4+
5+
![Daily code.json update](https://github.com/usepa/code-json-generator/workflows/Daily%20code.json%20update/badge.svg)
6+
7+
This application generates a machine-readable software inventory compliant
8+
with [Code.gov Metadata Schema version 2.0.0][1]. To accomplish this goal,
9+
the application connects to a series of Git hosting API "endpoints",
10+
inspects the configured projects, and generates an inventory. This application has been enhanced to automate the generation of the [Agency's code.json file](https://code-json-cg.app.cloud.gov/code.json) through GitHub Actions.
11+
12+
The application configuration supports internal/external hosting platforms
13+
with or without authentication (for private repositories). It currently works
14+
with GitHub and GitLab REST APIs but could easily be extended for other hosting
15+
platform APIs as well.
16+
17+
For each project, the application will attempt to use a developer-provided
18+
"code.json" snippet which is a JSON file containing the "releases" array
19+
for the project as defined by the [Code.gov Metadata Schema version 2.0.0][1].
20+
21+
If a "code.json" snippet file is not provided by the project maintainer, the
22+
application will attempt to infer sufficient/required properties from the
23+
target project and generate the best possible metadata for inclusion in the
24+
agency inventory.
25+
26+
Generating the code.json file
27+
---------------
28+
The code.json file can be generated by any of the GitHub Actions:
29+
30+
1. The [daily.yml](https://github.com/USEPA/code-json-generator/actions/workflows/daily.yml) generates the code.json file to this repository's [output branch](https://github.com/USEPA/code-json-generator/tree/output).
31+
32+
2. The [daily-deploy.yml](https://github.com/USEPA/code-json-generator/actions/workflows/daily-deploy.yml) generates the code.json file to this repository's [master branch](https://github.com/USEPA/code-json-generator/tree/master). Currently, this workflow is not active.
33+
34+
3. The [go-push (replacing Build and Deploy)](https://github.com/USEPA/code-json-generator/actions/workflows/go-push.yml) generates the code.json file to this repository's [master branch](https://github.com/USEPA/code-json-generator/tree/master) on the git push command. Currently, this workflow is not active.
35+
36+
Branch Directory
37+
---------------
38+
1. output - includes the code.json file generated by the [daily.yml](https://github.com/USEPA/code-json-generator/actions/workflows/daily.yml).
39+
2. cloudgov-deployment - provides intial code-json-generator GitHub Action workflow and removes 4000+ commit history generating the code.json file and deploying to cloud.gov.
40+
3. including-history and history-cloud.gov-deployment - provides intial code-json-generator GitHub Action workflow and includes 4000+ commit history generating the code.json file and deploying to cloud.gov.
41+
42+
43+
Getting Started - deploying to cloud.gov
44+
---------------
45+
46+
This section describes the process to acquire and run the code-json-generator
47+
application in cloud.gov with the daily-deploy.yml workflow.
48+
49+
### Prerequisites
50+
51+
This application is a command line Node application. Node must be installed
52+
on the system prior to running this application.
53+
54+
[https://nodejs.org/][2]
55+
56+
### Install the application
57+
58+
On the command line:
59+
```
60+
$ npm install -g code-json-generator
61+
```
62+
63+
### Configure the application runtime
64+
65+
The application requires a configuration file to dictate which repositories
66+
to include in the generated inventory. An [example configuration file][3]
67+
is provided to help get started.
68+
69+
1. Update the configuration file with your Agency's respective endpoints.
70+
2. Delete the existing create-agency-inventory-config.js file in the bin folder.
71+
3. Move the new configuration file from the etc folder into the bin folder.
72+
4. Rename the configuration file to create-agency-inventory-config.js.
73+
74+
Running locally or on cloud.gov
75+
-------------------------------
76+
You can run the code.json generator locally or deploy it to cloud.gov.
77+
78+
### Run the application locally
79+
80+
Running the application locally will help identify the specific repositories with missing or invalid code.json files. After all repositories have a valid code.json file, running the application will generate the Agency code.json locally.
81+
82+
The application provides command-line usage syntax help via the `--help` switch.
83+
```
84+
$ create-inventory.js --help
85+
86+
Usage: create-inventory [options]
87+
88+
Options:
89+
90+
-V, --version output the version number
91+
-c, --configFile <file> Configuration file
92+
-h, --help output usage information
93+
```
94+
To run the application locally, you need to:
95+
96+
1. Change the working directory to the bin folder.
97+
98+
2. To generate an inventory, run the application and provide a configuration file
99+
using the `--configFile <file>` switch. The generated inventory will, by
100+
default, be printed to STDOUT. This output can be redirected to a file
101+
for persistence.
102+
103+
```
104+
$ create-inventory.js --configFile ./create-agency-inventory.config.json > code.json
105+
```
106+
> Note: This example assumes a file containing proper configuration is located
107+
> in the current working directory and is called `create-agency-inventory.config.json`.
108+
> Adjust this usage to suit actual work environment.
109+
110+
Deployment to Cloud.gov with GitHub Actions
111+
-------------------------------------------
112+
You can deploy the app to Cloud.gov with GitHub Actions.
113+
114+
### Prerequisites
115+
To do this you will need a Cloud.gov account and the [Cloud Foundry Command Line Tools](https://github.com/cloudfoundry/cli#installers-and-compressed-binaries) installed on your machine.
116+
117+
1. Login to cloud.gov
118+
2. Navigate to your organization's space which the app will be deployed to.
119+
3. Follow the documentation to create a cloud.gov service account plan: [space deployer](https://cloud.gov/docs/services/cloud-gov-service-account/) for continuous deployment to Cloud.gov.
120+
4. Add the service key username as the CG_USERNAME secret in the GitHub Repository's Secrets.
121+
5. Add the service key username as the CG_USERNAME secret in the GitHub Repository's Secrets.
122+
123+
### Deploying to cloud.gov
124+
125+
You need to establish the name of your application before deploying it to cloud.gov.
126+
127+
1. Change the working directory to the etc/manifests folder.
128+
129+
2. Open the frontend.yml file.
130+
131+
3. Update the applications "name:" to whatever subdomain you wish to use (e.g., your-app-name).
132+
133+
4. Save, commit and push your changes.
134+
135+
5. You will see the code.json file located at: your-app-name.app.cloud.gov/code.json
136+
137+
### Update frequency of the Agency's code.json file
138+
139+
You can modify how frequently the Agency's code.json file is generated and published to cloud.gov.
140+
141+
1. Change the working directory to the .github/workflows folder.
142+
143+
2. Open the daily-deploy.yml file.
144+
145+
3. Update the `schedule` event per the desired frequency.
146+
147+
4. Save, commit and push your changes.
148+
149+
Agency code.json Daily update through GitHub Actions
150+
-------------------------------------------
151+
152+
GitHub Actions is being used to run a scheduled event to create the Agency's code.json file daily.
153+
154+
As mentioned earlier, if a "code.json" snippet file is not provided by the project maintainer, the
155+
application will attempt to infer sufficient/required properties from the
156+
target project and generate the best possible metadata for inclusion in the
157+
agency inventory.
158+
159+
The example EPA Agency code.json for the github.com/USEPA organization can be [found here](https://code-json-cg.app.cloud.gov/code.json).
160+
161+
Development
162+
-----------
163+
164+
To develop and possibly contribute to this project please review the
165+
[code of conduct][4] and [contributing guidelines][5].
166+
167+
### Obtain the source code
168+
169+
Potentially fork this repository and then clone the fork to obtain the source
170+
code.
171+
172+
```
173+
$ git clone <fork_urn>/code-json-generator.git
174+
$ cd code-json-generator
175+
```
176+
177+
### Develop in a feature branch
178+
179+
Updates should be developed in a feature branch on the local clone of a fork.
180+
```
181+
$ git checkout -b feature-X
182+
```
183+
184+
### Submit pull requests for review and integration
185+
186+
Commit changes to feature branches and push feature branches to the forked
187+
remote. Submit a pull request back to this upstream repository for review
188+
and integration. If the pull request fixes an open issue on this repository,
189+
include the text `fixes #N` (where `N` is the issue number fixed) in the
190+
pull request title or description.
191+
```
192+
$ git commit -am 'Implemented feature'
193+
$ git push origin feature-X
194+
```
195+
196+
197+
[1]: https://code.gov/#/policy-guide/docs/compliance/inventory-code
198+
[2]: https://nodejs.org/
199+
[3]: ./etc/config-example.json
200+
[4]: ./CODE_OF_CONDUCT.md
201+
[5]: ./CONTRIBUTING.md
202+
203+
### Credits
204+
205+
This repository reused material from the [USGS code-json-generator repository](https://github.com/usgs/code-json-generator/).
206+
207+
### Disclaimer
208+
209+
The United States Environmental Protection Agency (EPA) GitHub project code is provided on an "as is" basis and the user assumes responsibility for its use.  EPA has relinquished control of the information and no longer has responsibility to protect the integrity , confidentiality, or availability of the information.  Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by EPA.  The EPA seal and logo shall not be used in any manner to imply endorsement of any commercial product or activity by EPA or the United States Government.

0 commit comments

Comments
 (0)