Developer notes / Contributing

[raphaeltimbo]

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.

[josephcslater]

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]

Hello Raphael, Notes on how to develop code will be of great help to me and to anyone who have to contribute to this project. Here are my few suggestions: 1. While merging the files into contributing.rst, please ensure that the processes are in order for new people like me. 2. As Dr. Slater mentioned, I agree these should be for the users of the toolbox. * Where to find support in case of doubts on how to use the toolbox. * Explain where and how to report bugs * Installation (python, toolbox etc) procedure on different OS for Users/Students. 3. For developers, * Explain standards adopted for the project such as numpydoc conventions * Explain how to run tests * Steps to take before submitting to Github. It would be nice to have a checklist. I will think of something as I go ahead with more coding. Thank you for reaching out. Sincerely, Anusha Anisetti, Ph.D.

…

________________________________ From: raphaeltimbo <notifications@github.com> Sent: Tuesday, May 9, 2017 10:29:04 PM To: vibrationtoolbox/vibration_toolbox Cc: Anisetti, Anusha; Mention Subject: [vibrationtoolbox/vibration_toolbox] Developer notes / Contributing (#43) 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<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_josephcslater&d=DwMCaQ&c=3buyMx9JlH1z22L_G5pM28wz_Ru6WjhVHwo-vpeS0Gk&r=Rl6A8cr_hmtjGdvXY8WNGHgmX74-NHCGIXNQRFsVKlY&m=zjLL8sY7OF6qYLHBAXJo3cT-t0sO2MQ3ZB_IkBjpXtU&s=ePmAfzOsvLOnYOuybeV_J_MvjL2Csv_wCgbCUjx_VVI&e=> @AnushaAnisetti<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_AnushaAnisetti&d=DwMCaQ&c=3buyMx9JlH1z22L_G5pM28wz_Ru6WjhVHwo-vpeS0Gk&r=Rl6A8cr_hmtjGdvXY8WNGHgmX74-NHCGIXNQRFsVKlY&m=zjLL8sY7OF6qYLHBAXJo3cT-t0sO2MQ3ZB_IkBjpXtU&s=AsByK31h6-SIRmLLJfH2WHgtoxho9n_GJ2W0eeikO6A&e=> Regarding the content of the files, I think we should cover: * Where to find support in case of doubts on how to use the toolbox. * Explain where and how to report bugs. * Explain standards adopted for the project such as numpydoc conventions * Explain how to run tests * ... Feel free do add items here. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_vibrationtoolbox_vibration-5Ftoolbox_issues_43&d=DwMCaQ&c=3buyMx9JlH1z22L_G5pM28wz_Ru6WjhVHwo-vpeS0Gk&r=Rl6A8cr_hmtjGdvXY8WNGHgmX74-NHCGIXNQRFsVKlY&m=zjLL8sY7OF6qYLHBAXJo3cT-t0sO2MQ3ZB_IkBjpXtU&s=BDZm-j7bceIT-w_A-UlpB4VWqlCkubxjuY9sayClerA&e=>, or mute the thread<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_notifications_unsubscribe-2Dauth_ANceg-5FiZEv6a7rWkaLbjinZ2hPPtt4o7ks5r4SDwgaJpZM4NWGyU&d=DwMCaQ&c=3buyMx9JlH1z22L_G5pM28wz_Ru6WjhVHwo-vpeS0Gk&r=Rl6A8cr_hmtjGdvXY8WNGHgmX74-NHCGIXNQRFsVKlY&m=zjLL8sY7OF6qYLHBAXJo3cT-t0sO2MQ3ZB_IkBjpXtU&s=fUGrsQlyISpLojY9icQk8tkn2k6Acl9hdicHcDygP1Y&e=>.

[raphaeltimbo]

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]

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]

Of course! It is raphaelts@gmail.com

[josephcslater]

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

[josephcslater]

@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]

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]

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]

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.