Thanks for contributing! If you've started using Cloud Carbon Footprint, please add your name and organization to our list of adopters. Doing so helps our project!
Issues are created here.
Issues will be closed if they have been inactive and the latest affected version no longer receives support.
If an issue has been closed and you still feel it's relevant, feel free to ping a maintainer or add a comment!
We aim to be transparent in the work we are doing and have it posted on the project board.
If a particular card interests you, feel free to comment on it to inform us you'd like to collaborate so we can begin conversations about it.
Cards in the Ready to Do are properly prepared to be worked on.
If a card has the marker Good First Issue, it is a great option to start with. Please indicate via a comment in the card that you are working on it, and we will assign it to you and move it into the In Progress column. When you have finished, please submit a PR and we will review and merge it.
Cards without the Good First Issue marker are generally on our team's roadmap, but if you'd like to contribute that work, please comment on the ticket for alignment. Once you get to the point of working on the issue, please submit a PR with your changes and link it to the issue.
There are fundamentally three ways an individual can contribute:
- Open an issue: If you believe that you have found a new bug or have a feature addition or request, you should report it by creating a new issue in the
cloud-carbon-footprint/cloud-carbon-footprintissue tracker. - Help triage an open issue: You can do this either by providing assistive details (a reproducible test case that demonstrates a bug) or by providing suggestions to address the issue.
- Resolve an open issue: This can be done by demonstrating that the issue is not a bug or is fixed; but more often, by opening a pull request that changes the source in
cloud-carbon-footprint/cloud-carbon-footprintin a concrete and reviewable manner. We ask that as you do so, you consider tests you can write at various levels to help us ensure quality.
- Please join our Google Group and post a message with your question.
To submit a bug report:
When opening a new issue in the cloud-carbon-footprint/cloud-carbon-footprint issue tracker, users will be presented with a bug report template that should be filled in.
If you believe that you have found a bug in the cloud-carbon-footprint, please fill out the given template to the best of your ability.
It's common for open issues to involve discussion. Some contributors may have differing opinions, including whether the behavior is a bug or feature. This discussion is part of the process and should be kept focused, helpful, and professional.
Terse responses that provide neither additional context nor supporting detail are not helpful or professional. To many, such responses are annoying and unfriendly.
Contributors are encouraged to solve issues collaboratively and help one another make progress. If you encounter an issue that you feel is invalid, or which contains incorrect information, explain why you feel that way with additional supporting context, and be willing to be convinced that you may be wrong. By doing so, we can often reach the correct outcome faster.
Most issues are resolved by opening a pull request. The process for opening and reviewing a pull request is similar to that of opening and triaging issues, but carries with it a necessary review and approval workflow that ensures that the proposed changes meet the minimal quality and functional guidelines of the cloud-carbon-footprint project.
Pull Requests are the way concrete changes are made to the code, documentation, dependencies, and tools contained in the cloud-carbon-footprint/cloud-carbon-footprint repository. Please link your PR to an issue so we can more easily track the work being done
Fork the project on GitHub and clone your fork locally.
$ git clone [email protected]:[your-username-here]/cloud-carbon-footprint.git
$ cd cloud-carbon-footprint
$ git remote add upstream https://github.com/cloud-carbon-footprint/cloud-carbon-footprint
$ git fetch upstream
See the main repository README for build directions.
The Thoughtworks Cloud Carbon Footprint team uses Trunk-Based Development.
You're welcome to keep your local development environment organized as you like, however when submitting pull requests to the base repository, be sure to submit them against the trunk branch. In order to avoid merge conflicts in your pull request, you'll need to successfully rebase ahead of your pull request:
$ git fetch upstream
$ git rebase upstream/trunk
$ git push origin/trunk
If you are a core contributor, you may want to fetch changes from a forked repository. To make that easier, we have a script that will add the new remote and checkout the fork's branch. It can be invoked with:
$ ./scripts/remote_branch.sh remote-name remote-branch-name
Most pull requests opened against the cloud-carbon-footprint/cloud-carbon-footprint repository include changes to either the Typescript/React code in the client/ folder, the Typescript code in the packages/api/ folder or the documentation.
- We are using
eslintandprettierin the project - To avoid the hassle of manually linting the file, you can configure your IDE to automatically run the linter.
- If you are using Webstorm, check out this guide on how to set it up
- The prettier rules set up for the project are in
.prettierrc.jsonfile in the root DIR. - The client and the server have their own ESLint rules in the respective
.eslintrc.jsfiles. - Following the above rules is a pre-requisite for committing any code.
We strongly encourage you to cover any code added with the appropriate tests.
- Run
yarn testfrom the root directory. - If you are missing a test file in the coverage report, you may need to clear the test cache by running
yarn test:cleanfrom the client and / or server DIR.
- Run either
yarn headlessoryarn headedfrom theintegration_testsdirectory. Runningyarn headedwill run the tests with chrome browsers. - If using macOS Catalina or later, in order to run the tests properly, you will need to open your
System Preferences, navigate toSecurity & Privacy, selectScreen Recordingfrom the menu and then checkTestCafe Browser Tools.
These are also part of the pre-commit hook but it is also advisable to run tests regularly.
It is recommended to keep your changes grouped logically within individual commits. Many contributors find it easier to review changes that are split across multiple commits. There is no limit to the number of commits in a pull request. Please be sure to include your issue number in brackets and use easy to understand commit messages that summarize the work that you've done. A good commit message should describe what changed and why. See example below as reference.
$ git commit -m "[issue-number] Adds support for estimating Azure Anomoly Detector carbon emissions"
Please Note We have configured the repository to run secrets scanning (Talisman), dependency version check, tests and linting with a pre-commit hook. It is recommended you ensure this pre-commit hook is properly set up in your local environment, and to only commit from the command line to ensure that it runs.
Once you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.
$ git fetch upstream
$ git rebase upstream/trunk
This ensures that your working branch has the latest changes from cloud-carbon-footprint/cloud-carbon-footprint trunk.
While our tests run every time you commit thanks to the pre-commit hook described above, if you would like to run the tests independent of a commit, use the following:
$ yarn test
After committing your initial changes, it's important to remember that we have users who use the create-app version of our app and rely on the template files within that package.
To ensure that your changes are reflected in those template files, you will need to update the same files within the corresponding package of the packages/create-app/templates/default-app/packages directory.
Fortunately, we have a handy shell script to make this process easier. Using your terminal, you can utilize this script to copy the src directory of a package into the corresponding create-app template package's src directory.
To use the script, you can run the following command from the project's root directory:
scripts/update_templates.sh [package-name]
After successfully calling this command with a given package, you should get a confirmation message letting you know which directory has been updated. Make sure to keep the following in mind:
- The create-app templates only include the api, cli, and client packages. Passing another package name will result in an error.
- Template packages usually do not include test files or fixtures, therefore, the script will remove any test or fixture files that are copied over.
- Only the
srcdirectory of the given package will be copied over. For any files changed outside thesrcdirectory such as thepackage.json, you will need to manually copy those changes over. - Out of best practice, make sure to check any changed files prior to committing the results of this script using
git difforgit statusto ensure that all the changes you've made were properly copied over. Make sure to remove or rollback any changes that you did not work on.
Once you have committed your changes. run yarn changeset from the root directory. You will be prompted to choose which packages that need to be updated using the arrow keys and space bar. You will need to choose the appropriate update for each package that you have contributed to using the guidelines set with Semantic Versioning. You will also be prompted to leave a detailed description of your changes. This process will create a markdown file in the .changesets directory to be included in your commit and pushed. Changesets are only requested if you made an update to any of the packages.
If your changes required an update to any of the create-app templates, make sure to add a message including a link or reference to that commit in the generated changeset file. This helps anyone that is using a create-app version of the CCF tool easily make the appropriate updates to their app.
Example Markdown Message:
For changes to create-app templates, please refer to [this commit](https://github.com/cloud-carbon-footprint/cloud-carbon-footprint/commit/8fd171edb91cee5262c9d4d3a09fae6b7c265110).
Once your commits are ready to go -- with passing tests and linting -- begin the process of opening a pull request by pushing your working branch to your fork on GitHub.
$ git push origin my-branch
From within GitHub, opening a new pull request will present you with a template that should be filled out:
You will probably get feedback or requests for changes to your pull request. This is a big part of the submission process so don't be discouraged! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.
To make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
$ git add my/changed/files
$ git commit
$ git push origin my-branch
There are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.
Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something.
To contribute to the documentation, make sure you are in the microsite directory, then run the commands below.
yarn install # install the dependencies
yarn start # start a running instance of docusaurus
This will start a live-updating server show that will show any change you make the markdown files in microsite/docs/ as soon as they are saved.
From the client folder
- Run
yarn build -- --statsthen - Run
yarn webpack-bundle-analyzer build/bundle-stats.json
The above commands might be added to the package.json if we are so inclined
This will help in visualizing the bundle size, seeing bundles that might not be required in production, etc,.
We use GitHub Actions for our CI pipeline. Link to pipeline.
You can learn more about GitHub Actions in the Github Actions Documentation
When pushing up, GitHub Actions will automatically go through the steps of deploying to staging as long as all tests and linting past.
To deploy to production, go to GitHub Actions and view the CI workflow to deploy. It is a manual approval, therefore if it is ready to be pushed into production, click on "Review deployments", select production, then approve the deployment.
- We use yarn for package management.
- To install a new package, use
yarn add package-name(production) oryarn add --dev package-name(development) inside either the client or server directory. - Use
yarn installat the root directory to have all packages freshly installed.
- To update a package to the patch or minor version, use the command
yarn update <package-name> - To update a package to the latest major version, use
yarn upgrade --latest <package-name>
We record any significant architectural choices we make with lightweight adr files, located in the .adr folder. There is a template included as well. For more information about Lightweight ADR's, see ThoughtWork's Technology Radar.
- Used to check for potential secrets or sensitive information
- This will run along every pre-commit hook
- You can learn more about Talisman here
- We are using Winston for logging locally and Google's logging-winston for Logging in Google App Engine.
- The LOGGING_MODE can set inside the api/.env file, but by default it should be unset for local development.
- packages/api/logs contain the log files that written to by the logger. This should be deleted occasionally, otherwise it will become unnecessarily large.
-
Open the TypeScript tool window (View | Tool Windows | TypeScript) and switch to the Errors tab. The tab lists the discrepancies in the code detected by the TypeScript Language Service. The list is updated dynamically as you change your code for easier and faster debugging.
-
You can also monitor compilation errors by going to the TypeScript tool window (View | Tool Windows | TypeScript), and switching to the Compile errors tab which shows up only after first manual compilation, when you click the 🔨 button and select the compilation scope.
-
packages/api/logs contain the log files that written to by the logger. This should be deleted occasionally, otherwise it will become infinitely large.
-
Delete estimate.cache.json to pull new data when testing to get most up to date data and verify querying is working as expected
- To run test on IDE, install the extension,
Jest Runner, from marketplace
If GCP credentials are not linked properly, there may be an error regarding AWS credentials not being set properly. This has been caused by either out of date credentials on GCP, or the GCP credentials not being set properly on the local environment
- If you are receiving the following error, you may have installed Talisman wrong
sh: /talisman_hook_script: No such file or directory error. - To resolve check your env var by
echo $TALISMAN_HOME, if it is installed correctly it will echo out a path/Users/username/.talisman/bin. If not, please refer to the README.md for instructions to install talisman - If this variable is set, check to make sure you have the /talisman_hook_script within that directory
- If there is an invalid check from Talisman, the failed commit will contain a checksum that you can add to the .talismanrc, which will allow it to pass for that commit.
- However this checksum is only valid for that specific commit, if the file changed, and it has a talisman check, it will run a new checksum for the .talismanrc that will have to be updated
- If you have another process running on localhost:3000 when the integration tests run, they will fail. This can happen when you are already running the client package, or the microsite. Please stop this process before re-running the integration tests.
© 2021 Thoughtworks, Inc.