From 55707fb470fbc9e1622e33d9c5196c43ce2bd28c Mon Sep 17 00:00:00 2001 From: Albert Buchard Date: Wed, 9 Aug 2023 21:34:12 +0200 Subject: [PATCH] #2 Add contribution rules and templates (#3) --- .github/ISSUE_TEMPLATE/bug_report.md | 38 +++++++ .github/ISSUE_TEMPLATE/feature-proposal.md | 28 +++++ CONTRIBUTING.md | 114 +++++++++++++++++++++ README.md | 11 +- 4 files changed, 188 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature-proposal.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..dd84ea7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + - OS: [e.g. iOS] + - Browser [e.g. chrome, safari] + - Version [e.g. 22] + +**Smartphone (please complete the following information):** + - Device: [e.g. iPhone6] + - OS: [e.g. iOS8.1] + - Browser [e.g. stock browser, safari] + - Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature-proposal.md b/.github/ISSUE_TEMPLATE/feature-proposal.md new file mode 100644 index 0000000..ff55d89 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-proposal.md @@ -0,0 +1,28 @@ +--- +name: Feature proposal +about: 'Detail and discussing a new feature proposal ' +title: Short description of the core feature intent +labels: feature +assignees: albertbuchard + +--- + +**Feature Proposal Template** + +**Feature Overview**: +Provide a concise description of the feature. + +**Problem to Solve**: +Explain the problem or limitation this feature addresses. Why is this feature needed? + +**Desired Solution**: +Describe how you envision this feature working. If possible, provide examples or mock-ups. + +**Alternative Solutions**: +Are there any alternative solutions or features you've considered? + +**Additional Context**: +Provide any other context or details about the feature proposal here. This can include challenges you're facing, reasons for the proposal, etc. + +**Priority**: +(Optional) If you have a sense of how urgent this feature is, indicate here. For example: low, medium, high, critical. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1ae9a84 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,114 @@ +# Contributing to `slurm-pytorch-ddp-boilerplate` + +First off, thank you for considering contributing to `slurm-pytorch-ddp-boilerplate`. It's people like you that make this project such a great tool. + +## Table of Contents + +1. [Getting Started](#getting-started) +2. [How to Contribute](#how-to-contribute) +3. [Branching Strategy](#branching-strategy) +4. [Pull Request Process](#pull-request-process) +5. [Issue Labels](#issue-labels) +6. [Additional Notes](#additional-notes) + +--- + +## Getting Started + +- **Fork** the repository to your GitHub account. +- **Clone** your forked repository and navigate to the directory: + ```bash + git clone https://github.com/YOUR_USERNAME/slurm-pytorch-ddp-boilerplate.git + cd slurm-pytorch-ddp-boilerplate + ``` +- **Add** the main repository as a remote to keep in sync: + ```bash + git remote add upstream https://github.com/albertbuchard/slurm-pytorch-ddp-boilerplate.git + ``` + +- **Synchronize** your fork with the main repository: + ```bash + git fetch upstream + git checkout development + git merge upstream/development + ``` + +- **Propose or take on an issue** to work on. If you're unsure where to start, check out the [issues](https://github.com/albertbuchard/slurm-pytorch-ddp-boilerplate/issues) section. +- Always work on a **new branch** for your changes, referencing the issue number: + ```bash + git checkout -b issue-#-descriptive-title development + ``` + +- Make your changes, **commit** them, and **push** to your fork: + ```bash + git add . + git commit -m "Descriptive commit message about your changes" + git push origin issue-#-descriptive-title + ``` + +- Finally, navigate to your fork on GitHub and click the `New pull request` button to start the process of creating a PR to the `development` branch of the main repository. + +- Be sure to follow the [Pull Request Process](#pull-request-process) below. + +--- + +## How to Contribute + +1. **Feature Proposals**: + - For proposing a new feature, use the **Feature Proposal Template** available in the issues section. + - Fill in the template with as much detail as possible. The clearer and more comprehensive your proposal, the faster we can collaborate and discuss. + +2. **Bug Reports**: + - If you've identified a bug, use the **Bug Report Template** to provide information about the problem. + - Clearly describe the issue, including steps to reproduce and any relevant details about your configuration. + +3. **Improving Documentation**: + - Documentation is crucial! If you see an area that could use improvement or lacks clarity, please propose your changes. + +4. **Reviewing Pull Requests**: + - If you're looking to provide feedback, consider reviewing open pull requests. Your insights and review comments can guide the project to even higher standards. + +--- + +## Branching Strategy + +- The `master` branch is the main branch where the source code reflects a production-ready state. +- The `development` branch is the main branch for ongoing development. Contributors should always create a new branch off of `development` and submit pull requests back into this branch. +- Periodically, the changes from the `development` branch will be merged into `master` and tagged with a release number. + +--- + +## Pull Request Process + +1. **Submit to `development`**: Always direct your pull requests to the `development` branch, not `master`. + +2. **Title Format**: Please format your PR titles as `#IssueNumber Descriptive Title`. + - Example: `#23 Add user authentication support` + +3. **Description**: In the PR description, provide a detailed overview of the changes, the motivation behind them, and any additional context that might be useful for reviewers. + +4. **Link Related Issues**: If your PR resolves any open issues, mention them in the description to create a link between the PR and issue. + +5. **Review**: Once your PR is submitted, it'll be reviewed by the maintainers. Address any feedback or changes requested. + +6. **Merging**: Once your PR is approved, it will be merged into the `development` branch. Periodic merges from `development` to `master` represent new versions of the project. + +--- + +## Issue Labels + +The `bug` and `feature` labels are the main ones used to categorize issues and pull requests. +Other labels provide additional information about the issue or pull request. +The `question` label should not be used on its own, as questions should be asked in the discussion forum. + +--- + +## Additional Notes + +- Ensure your code adheres to the existing style for consistency. +- Before submitting a large PR, consider opening an issue to discuss the changes and get feedback. +- Always aim for clear, concise, and well-commented code. This makes it easier for others to understand and build upon your contributions. + +--- + +Thank you for your contributions! \ No newline at end of file diff --git a/README.md b/README.md index 79cb365..e384760 100644 --- a/README.md +++ b/README.md @@ -266,11 +266,12 @@ The `main.py` serves as the primary entry point for the boilerplate and offers a 1. Instantiate the `DistributedWandb` class: ```python + from src.ddp.distributed_wandb import DistributedWandb wandb = DistributedWandb(every_process=False, project="Your_Project_Name") ``` 2. Log data: - + ```python wandb.log({"loss": loss_value}) ``` @@ -317,11 +318,15 @@ During the development of this boilerplate, various learnings emerged that could - Account information: `sacct` - User-specific queue: `squeue -u ` ---- +--- ## Contributing -Feel free to fork this repository, make your changes, and submit pull requests. We appreciate any contributions that can enhance the capabilities of this boilerplate! +Your contributions to `slurm-pytorch-ddp-boilerplate` enrich the project and benefit all users. + +Whether you're improving documentation, reporting bugs, suggesting features, or writing code, we appreciate your efforts. + +For a clear step by step on how to contribute, please refer to the [contributing guidelines](CONTRIBUTING.md). ---