Skip to content

Latest commit

 

History

History
246 lines (177 loc) · 10.8 KB

CONTRIBUTING.md

File metadata and controls

246 lines (177 loc) · 10.8 KB
Raw

Contributing Guidelines

Key Points to Note:

  • Not Absolute Truths: the information herein is not exhaustively curated and is subject to change.

  • Reference Official Documentation: In case of uncertainty, it's always better to consult the official documentation, relevant books, or content provided by our great professors.

  • Open to Suggestions: Your participation in this project is highly valued. So feel free to open an Issue or Pull Request to propose enhancements to this guide.

Main Software Engineering Book References

One highly recommended resource is Software Engineering at Google, a treasure trove of best practices and insights from Google’s software development experiences. While a detailed summary will be added later, we encourage all contributors to explore this book for a deeper understanding of collaborative software engineering.

Guidelines

Adopting standards in software development is essential for consistency, readability, and collaboration. Standards simplify the complexity of collaborative projects and support automation processes such as Semantic Versioning and Releases.

Git

Understanding Git is crucial for our workflow. While the VS Code extension for Git is a time-saver, knowing how to use Git CLI is fundamental. For quick reference, consult the Git Cheat Sheet.

Relevant Links:

Branch Methodology

We follow GitHub Flow, a straightforward and effective branch-based workflow. GitHub Flow is a lightweight, branch-based workflow that emphasizes collaboration, review, and prompt integration. It involves creating branches for new features or fixes, implementing changes, opening PRs for review, revising, merging against main, and then deleting the feature branch upon completion. Ultimately, the main branch is the primary source of truth. For a more in-depth discussion, see Software Engineering at Google book - Version Control and Branch Management Chapter.

Relevant Links:

Commit Message Convention

We adhere to Conventional Commits standards:

<type>: <short summary> ( #<pull-request-reference> )
  │           │                       |
  |           |                       └─⫸ The PR reference number.
  |           |
  │           └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │
  └─⫸ Commit Type: feat|feat!|fix|fix!|perf|perf!|refactor|refactor!|test|bench|build|ci|docs|style|chore
Commit Types:
Type Description Example
feat add a new feature feat: add linear algebra solver for Computational Mathematics module
feat! a breaking change to a feature feat!: add linear algebra solver for Computational Mathematics module
fix a bug fix fix: correct data preprocessing bug in ML project
fix! a breaking change to a bug fix fix!: correct data preprocessing bug in ML project
perf a code change that improves performance perf: optimize pipeline for reduced training time
perf! a breaking change to a performance improvement perf!: optimize pipeline for reduced training time
refactor a code change that neither fixes a bug nor adds a feature refactor: optimize pipeline for reduced training time
refactor! a breaking change to a refactoring refactor!: optimize pipeline for reduced training time
test adding missing tests or correcting existing tests test: add unit tests for data preprocessing pipeline
bench improvements to benchmarks bench: improve performance of data preprocessing pipeline
build changes to build system or external dependencies build: update dependencies for Data Science module
ci changes to CI configuration files and scripts ci: update CI configuration for Data Science module
docs documentation only changes docs: update README for Modern Programming Methods
style changes that do not affect the meaning of the code style: update code formatting for Data Science module
chore changes to the build process or auxiliary tools and libraries chore: update dependencies for Data Science module
Commit Rules:
  1. Follow the commit naming convention.
  2. Be concise and descriptive.
  3. Use English.
  4. Start with a verb in imperative mood.
  5. Use present tense.
  6. Avoid ending with a period.
Relevant Links:

Branch Naming Convention

Branch names should be descriptive, following this format:

<type>/<issue-reference>/<description>
  │           │                |
  |           |                └─⫸ A short description of the branch's purpose.
  |           |
  │           └─⫸ The github issue/ticket number. Use `no-ref` if no issue.
  │
  └─⫸ Branch Type: feat|feat!|fix|fix!|perf|perf!|refactor|refactor!|test|bench|build|ci|docs|style|chore
Branch Name Examples:
  • fix/no-ref/update-dependencies
  • fix/issue-27/fix-data-sync-error
  • test/no-ref/refactor-math-algorithms
  • feature/issue-15/implement-regression-analysis
Relevant Links:

Pull Requests (PRs) and Code Reviews

PRs are vital for proposing and reviewing changes. Reviewers ensure code quality, while contributors address feedback for merge-readiness. According to Software Engineering at Google - Code Review Chapter, code reviews are key for knowledge sharing and documentation. PR titles should follow the same commit naming convention as before:

<type>: <short summary> ( #<pull-request-reference> )
  │           │                       |
  |           |                       └─⫸ The PR reference number.
  |           |
  │           └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │
  └─⫸ Commit Type: feat|feat!|fix|fix!|perf|perf!|refactor|refactor!|test|bench|build|ci|docs|style|chore
PR Description Template: 
## Why this PR?
- Explain the need.

## What Changes?
- Summarize changes.

## Tests added?
- State test status.

## Breaking changes created?
- Highlight any disruptions.

## Additional context?
- Provide more information.
PR Description Example: 
## Why this PR?
- To address performance issues in our ML model training process.

## What Changes?
- Enhanced the DataPreprocessing class in data_processing.py.

## Tests added?
- Comprehensive unit tests were included.

## Breaking changes created?
- None.

## Additional context?
- Related to issue #1234 and reviewed by the data science team.
PR Rules:
  • PR titles must follow the commit naming convention.
  • PR descriptions should adhere to the template.
  • Link PRs to relevant issues.
  • Ensure PRs are reviewed by knowledgeable team members.
  • Tag PRs appropriately.
  • Assign PRs to responsible individuals.
  • Link PRs to milestones and projects.
  • PRs must pass automated checks.
  • Use Squash and Merge for merging.
  • PRs should be up-to-date with main.
Relevant Links:

Issues

TODO: Provide guidelines for effective issue management.

Code Style

TODO: Define code style guidelines.

Continuous Integration and Deployment

TODO: Detail our CI/CD practices.

Semantic Versioning and Releases

TODO: Explain versioning and release management.

Semantic Versioning and Releases

TODO: Explain versioning and release management.

Collaboration and Communication

TODO: Outline collaboration and communication protocols.

Code of Conduct

This file was crafted with the assistance of ChatGPT.