Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve CONTRIBUTING.md #609

Closed
cpaniaguam opened this issue Dec 9, 2024 · 1 comment · Fixed by #610
Closed

docs: improve CONTRIBUTING.md #609

cpaniaguam opened this issue Dec 9, 2024 · 1 comment · Fixed by #610
Assignees

Comments

@cpaniaguam
Copy link
Collaborator

  1. Add clarification, remove ambiguity

1. Expanding the existing codebase with new features or improvements to existing ones. Use the "Feature Request" label.
2. Contributing to or improving the project's documentation and examples (located in `hssm/examples`). Use the "Documentation" label.
3. Rectifying issues with the existing codebase. These can range from minor software bugs to more significant design problems. Use the "Bug" label.

It's not clear to me where/when these labels are to be used. Should an issue be created first and add the suggested label? Or should the labeling be used in a PR?

It feels like this block should be under the Opening Issues section. That would clarify where the labeling should be used.

  1. Add definitions/descriptions

The preferred workflow for contributing to HSSM is to fork the GitHub repository, clone it to your local machine, and develop on a feature branch.

I think expanding the meaning of fork, clone, feature branch would be beneficial. Maybe adding short definitions/descriptions would be useful for new contributors reading this guide.

  1. Remove SSH commands
    `SSH`
    ```
    git clone [email protected]:<your GitHub handle>/lnccbrown/hssm.git
    ```

    `SSH`
    ```
    cd hssm
    git remote add upstream [email protected]:lnccbrown/hssm.git
    ```

I think that if people are using ssh, they are very likely to understand this workflow already. I'd remove these commands to make the document simpler.

  1. Inform of best practices early
    > Warning: Always create a new feature branch before making any changes. Make your changes in the feature branch. It’s good practice to never routinely work on the main branch of any repository.

Suggestion

Warning

Routinely making changes in the main branch of a repository should be avoided. Always create a new feature branch before making any changes and make your changes in the feature branch.

  1. Remove listing about poetry installing

It's not clear to me why this is required/advantageous. Can't users add their changes locally and test them without poetry? I think this section would need to be expanded (in a separate advanced subsection?) if new dependencies are needed and how to use poetry to manage that.

Thoughts? @digicosmos86 @AlexanderFengler

@AlexanderFengler
Copy link
Collaborator

Re 1:
These are probably meant more as high level concepts that specific contribution guidelines at that point. It's an option to expand it into concrete guidelines for labeling PRs not against it.

Re 2:
Agree that we should probably add short definitions on this (possibly some links)

Re 3:
Agree

Re 4:
Agree

Re 5:
Also agree that it's probably best to not make it seem that poetry is a must.

Thanks @cpaniaguam.

@cpaniaguam cpaniaguam self-assigned this Dec 12, 2024
@cpaniaguam cpaniaguam linked a pull request Dec 12, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants