Skip to content

docs: improve CONTRIBUTING.md #609

@cpaniaguam

Description

@cpaniaguam
  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 git@github.com:<your GitHub handle>/lnccbrown/hssm.git
    ```

    `SSH`
    ```
    cd hssm
    git remote add upstream git@github.com: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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions