From cd9efb1f53c987b2617f4e23522514766ee33802 Mon Sep 17 00:00:00 2001 From: Sukriti Sharma Date: Wed, 13 Mar 2024 11:31:37 -0600 Subject: [PATCH] Update CONTRIBUTING.md (#86) * Update CONTRIBUTING.md Signed-off-by: Sukriti Sharma * add architecture record templates Signed-off-by: Sukriti-Sharma4 * update link Signed-off-by: Sukriti-Sharma4 * update broken link Signed-off-by: Sukriti-Sharma4 --------- Signed-off-by: Sukriti Sharma Signed-off-by: Sukriti-Sharma4 --- CONTRIBUTING.md | 12 ++++---- architecture_records/template.md | 51 ++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 5 deletions(-) create mode 100644 architecture_records/template.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 375096ed7..4df74d20f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,9 +19,10 @@ The below workflow is designed to help you begin your first contribution journey Help on open source projects is always welcome and there is always something that can be improved. For example, documentation (like the text you are reading now) can always use improvement, code can always be clarified, variables or functions can always be renamed or commented on, and there is always a need for more test coverage. If you see something that you think should be fixed, take ownership! Here is how you get started: ## How Can I Contribute? -TODO: Add link to ADR and add template to this repository -For any contributions that need design changes/API changes, first contribute an ADR. Reason for ADR: teams agree on the design, to avoid back and forth after writing code. An ADR gives context on the code being written. +NOTE: Before making any contribution, please ensure the content does not include any IBM proprietary information or any specific information about IBM products. + +For any contributions that need design changes/API changes, reach out to maintainers to check if an Architectural Design Record would be beneficial. Reason for ADR: teams agree on the design, to avoid back and forth after writing code. An ADR gives context on the code being written. If requested for an ADR, make a contribution [using the template](./architecture_records/template.md). When contributing, it's useful to start by looking at [issues](https://github.com/foundation-model-stack/fms-hf-tuning/issues). After picking up an issue, writing code, or updating a document, make a pull request and your work will be reviewed and merged. If you're adding a new feature or find a bug, it's best to [write an issue](https://github.com/foundation-model-stack/fms-hf-tuning/issues/new) first to discuss it with maintainers. @@ -29,9 +30,10 @@ To contribute to this repo, you'll use the Fork and Pull model common in many op Guide](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md) from Kubernetes. -When your contribution is ready, you can create a pull request. Pull requests are often referred to as "PR". In general, we follow the standard [GitHub pull request](https://help.github.com/en/articles/about-pull-requests) process. Follow the template to provide details about your pull request to the maintainers. It's best to break your contribution into smaller PRs with incremental changes, and include a good description of the changes. +When your contribution is ready, you can create a pull request. Pull requests are often referred to as "PR". In general, we follow the standard [GitHub pull request](https://help.github.com/en/articles/about-pull-requests) process. Follow the template to provide details about your pull request to the maintainers. It's best to break your contribution into smaller PRs with incremental changes, and include a good description of the changes. +We require new unit tests to be contributed with any new functionality added. -Before sending pull requests, make sure your changes pass formatting, linting and unit tests. +Before sending pull requests, make sure your changes pass formatting, linting and unit tests. These checks will run with the pull request builds. Alternatively, you can run the checks manually on your local machine [as specified below](#development). #### Code Review @@ -50,7 +52,7 @@ This section guides you through submitting a bug report. Following these guideli #### How Do I Submit A (Good) Bug Report? -Bugs are tracked as [GitHub issues using the Bug Report template]((https://github.com/foundation-model-stack/fms-hf-tuning/issues/new?template=bug_report.md). Create an issue on that and provide the information suggested in the bug report issue template. +Bugs are tracked as [GitHub issues using the Bug Report template](https://github.com/foundation-model-stack/fms-hf-tuning/issues/new?template=bug_report.md). Create an issue on that and provide the information suggested in the bug report issue template. ### Suggesting Enhancements diff --git a/architecture_records/template.md b/architecture_records/template.md new file mode 100644 index 000000000..802ab82e8 --- /dev/null +++ b/architecture_records/template.md @@ -0,0 +1,51 @@ +# Title of ADR, keep it concise + +**Deciders(s)**: +**Date (YYYY-MM-DD)**: +**Obsoletes ADRs**: +**Modified By ADRs**: +**Relevant Issues**: + +- [Summary and Objective](#summary-and-objective) + - [Motivation](#motivation) + - [User Benefit](#user-benefit) +- [Decision](#decision) + - [Alternatives Considered](#alternatives-considered) +- [Consequences](#consequences) +- [Detailed Design](#detailed-design) + +## Summary and Objective + +Context goes here. + +Describe the forces at play, including technological, political, social, and project local. These forces are likely in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. + +### Motivation + +Why this is a valuable problem to solve? What background information is needed to show how this design addresses the problem? + +Which users are affected by the problem? Why is it a problem? What data supports this? What related work exists? + +### User Benefit + +How will users (or other contributors) benefit from this work? What would be the headline in the release notes or blog post? + +## Decision + +This is the meat of the document, where you explain the decision. If you have multiple alternatives, be sure to use sub-sections for better separation of the idea, and list pros/cons to each approach. If there are alternatives that you have eliminated, you should also list those here, and explain why you believe your chosen approach is superior. + +Make sure you’ve thought through and addressed the following sections. If a section is not relevant to your specific proposal, please explain why, e.g. your ADR addresses a convention or process, not an API. + +### Alternatives Considered + +- Make sure to discuss the relative merits of alternatives to your proposal. + +## Consequences + +Describe the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. + + +## Detailed Design + +This section is optional. Elaborate on details if they’re important to understanding the design, but would make it hard to read the proposal section above. +