Skip to content

Developer notes / Contributing #43

Open
@raphaeltimbo

Description

Currently we have some files inside the project that give some guidance on how to develop code for this project, but I think it would be good if we could discuss which files we should have and what they should contain.
Currently we have notes on:
readme.rst
vibration_toolbox/readme.rst
developer_notes.rst
create_distro.rst

I believe we could merge some of these files in a CONTRIBUTING.rst or something like that, just to make it easier to get the information.
Would like to hear your opinions @josephcslater @AnushaAnisetti

Regarding the content of the files, I think we should cover:

EDITING THIS PART AS WE DISCUSS

  • Where to find support in case of doubts on how to use the toolbox.

    Explain where and how to report bugs.

CONTRIBUTING.rst See #42

  • Explain standards adopted for the project such as numpydoc conventions

    Explain how to run tests

    Steps to take before submitting to Github.

    ...

Feel free do add items here.

Activity

josephcslater

josephcslater commented on May 10, 2017

@josephcslater
Member

I agree. You are seeing how I address my memory as I get older- I leave notes where I need them. I this case, taking seconds to jot things down potentially saves hours. However, there is enough that it is messy and should be consolidated.

FWIW: Anusha is not new to Python, but very fresh, more so than I was over a year ago. So, she will certainly need our support. She is not new to modeling mechanics/vibration, but to the language and all of the structure of a project. I only started to learn how to put together a project with you last year. I have more students who will likely be joining in and this may very well be used as a place they can try things (of course, without them having the ability to merge without approval).

So: I like the name you give. I support 100% compatibility with NumPy practices and standards. Making it rst may be kinder than markdown as I do anticipate this being an entry point for programming (keeping the two straight in my head sometimes baffles me).

Second, I think it should steer non-developers directly to the manual. Likewise, the manual should steer prospective developers to this document. By doing this, they each can focus on the intended audience.

With that, the manual should contain:

  1. Where to find support in case of doubts on how to use the toolbox.

  2. Explain where and how to report bugs.

  3. ...

While the CONTRIBUTING.rst file should contain

  1. Explain standards adopted for the project such as numpydoc conventions

  2. Explain how to run tests Adding how to run tests on developer notes. #42

  3. Expected practices (forking/pull requests). I've only given Raphael and myself the ability to directly change the main fork. Branching can be tedious, but I think it's best to keep the number of direct hands controlled. Anusha still needs oversite more than either of us. You've had better behavior than I in forking and merging, but I will likely not be doing as much of my own forks as others. I'll be helping, guiding, and managing more than contributing in a major way as I'll be focused on my other two major projects... neither of which is yet off the ground.

  4. ...

The MAKEFILE now has help, so some of the documentation on making releases is no longer necessary.

AnushaAnisetti

AnushaAnisetti commented on May 10, 2017

@AnushaAnisetti
Contributor
raphaeltimbo

raphaeltimbo commented on May 11, 2017

@raphaeltimbo
CollaboratorAuthor

I have updated my initial comments based on your replies.
I have changed the developer_notes.rst file to CONTRIBUTING.rst.
Inside the contributing file I have tried to describe the process to contribute code and I have also added a final section to main developers (with things like how to make distribution).
If you all agree I think it is safe to delete the readme.rst file inside the /docs and the create_distro.rst.

Regarding the first part "Where to find support in case of doubts on how to use the toolbox." do you think it would be ok to refer to the github/issues as well? Normally projects have a forum or mailing list for this kind of stuff, but since we don't have that, I think it would not be a bad think (at least for now) to use the issues part for this purpose.

AnushaAnisetti

AnushaAnisetti commented on May 14, 2017

@AnushaAnisetti
Contributor

Raphael,

Could you please provide me your e-mail ID for few developer questions? I will not take much time.
I can be reached at anisetti.2@wright.edu

raphaeltimbo

raphaeltimbo commented on May 15, 2017

@raphaeltimbo
CollaboratorAuthor

Of course! It is raphaelts@gmail.com

josephcslater

josephcslater commented on May 15, 2017

@josephcslater
Member

@raphaeltimbo Yes, directing to issues is appropriate. Do you think we need to set up a mailing list? Wow- this has developed quickly.

josephcslater

josephcslater commented on May 15, 2017

@josephcslater
Member

@raphaeltimbo I updated CONTRIBUTING.rst. Note that most of the "help docs" were made unnecessary by the Makefile.

We could add "pull-request" as an option which would run pytest, commit, etc. if you think that would be helpful? It may be for @AnushaAnisetti as she isn't Unix experienced, but she may have make working now.

raphaeltimbo

raphaeltimbo commented on May 15, 2017

@raphaeltimbo
CollaboratorAuthor

Regarding the pull-request command in the make file, that could be an option, but I don't know how that would be implemented since my knowledge of 'make' is not that much.
I actually tend to use pycharm git integration to commit and then push new branches to the repository. After that I use the github site to open the pull-request and to check if travis is passing.

josephcslater

josephcslater commented on May 15, 2017

@josephcslater
Member

So, I only learned to create the Makefile recently. You only need use it.

From the top of the repository, in a terminal, you can type make and it will provide help (added a few days ago).

There is a slew of commands for building distribution files, documents, making releases, pushing to pypi, etc. So, my making the Makefile took out the need for my own instructions (as they are listed as instructions for each operation in the Makefile.).

I've never used the pycharm git tools. I'm mostly using spyder and jupyter for my work, although I then use Atom for "cleanup". Atom has git integration as well, but I tend to use the github app (I'm on a Mac), although I've started to really like GitKraken, which is multiplatform and gives a nice visualization of what's going on.

raphaeltimbo

raphaeltimbo commented on May 16, 2017

@raphaeltimbo
CollaboratorAuthor

Regarding the mailing list, I would prefer to use only the issues. I think that is better if we keep things in only one. I thing I notice is that we can label an issue as a question, using that we can keep track of the real bugs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Assignees

No one assigned

    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

      Developer notes / Contributing · Issue #43 · vibrationtoolbox/vibration_toolbox